PySpur: a visual playground for agentic workflows that stays Python at the core

The problem PySpur targets: prompt tweaking, blind workflows, raw JSON

The README names three failures it was built against: prompt hell, workflow blindspots, and terminal testing. That framing is not marketing filler. Anyone who has shipped an agent knows the loop: change a prompt, rerun the whole chain, squint at a JSON blob, guess which step broke. PySpur's answer is to make the graph visible and the intermediate outputs inspectable, so a failing step is a node you can open rather than a line in a log.

The intended user is an AI engineer, not a no-code operator. The README says AI engineers use PySpur to iterate visually "without reinventing the wheel," and the development setup expects Python and TypeScript work. The project ships a node editor, but the extension path is a Python file. That combination is the actual positioning: a UI over a codebase you still own.

How the graph, traces and human breakpoints fit together

PySpur models an agent as a directed graph of nodes. The README lists the node-level capabilities that matter: loops with memory for iterative tool calling, structured outputs edited through a JSON Schema UI, RAG nodes that parse, chunk, embed and upsert into a vector database, and multimodal input covering video, images, audio, text and code. Tools are also nodes, with Slack, Firecrawl.dev, Google Sheets and GitHub named as examples.

Execution produces traces. The README says traces are captured automatically for deployed agents, and evals run an agent against real-world datasets. Human-in-the-loop breakpoints are the interesting mechanism: the documentation states these pause the workflow when reached and resume whenever a human approves, which means the workflow state has to persist across the pause. That is why the README recommends PostgreSQL over SQLite for a stable experience. A workflow that waits for approval is a workflow that holds state, and a file-backed database is a weaker place to hold it.

Extensibility is deliberately narrow. The README says you add new nodes by creating a single Python file. There is no plugin manifest described, no separate SDK documented. For a team already comfortable in Python, that is a lower barrier than learning a DSL. For a team that wants a marketplace of prebuilt integrations, it is not that.

Installing PySpur and running a first workflow on port 6080

The README gives a pip path as the quickest start and requires Python 3.11 or higher. Install the package first:

pip install pyspur

Then scaffold a project directory. The README states this creates a new directory containing a .env file:

pyspur init my-project
cd my-project

Start the server. By default the README says the app comes up at http://localhost:6080 backed by SQLite:

pyspur serve --sqlite

After the server reports it is running, open http://localhost:6080 in a browser. To add provider keys, the README offers two routes: the API Keys tab in the app UI, or editing the .env file directly. Editing .env is also where the README recommends configuring a PostgreSQL URL instead of SQLite, and restarting with pyspur serve once that is done. If you prefer containers, the repository provides a compose file, and the README's development path uses it:

docker compose -f docker-compose.dev.yml up --build -d

Where PySpur is the wrong tool

The clearest boundary is in the development setup: the README states that the instructions are for Unix-like systems and that development on Windows/PC is not supported. If your team is standardized on Windows workstations, the dev container path is closed to you and the manual path is documented only for Unix-like systems. That is a hard constraint, not a preference.

The second boundary is operational. The README does not document rollback, and it does not describe a migration procedure beyond the presence of generate_migrations.sh in the repository root. Versioned workflows, staged promotion, or a way to revert a deployed agent to a previous graph are not described. Teams that need audited change control over agent definitions should treat that as an open question rather than assume it exists.

Third, the README recommends PostgreSQL for stability but the quick start uses SQLite. That gap is fine for a laptop demo and questionable for anything with concurrent users or long-lived approval breakpoints. If you cannot run PostgreSQL, PySpur is probably not the right fit for production work.

PySpur against Langflow, Flowise and Dify

The related searches around PySpur are mostly other tools: Langflow, Flowise, Dify, TaskingAI. The honest difference is where the code lives. PySpur's README insists on Python as the extension surface, with new nodes written as a single Python file, and the repository is split into backend/ and frontend/ with a TypeScript frontend. Langflow and Flowise are also visual builders, but the comparison that matters is not the canvas, it is whether the artifacts you produce are Python you can read and version, or configuration that lives inside the tool.

Dify moves further toward a hosted platform with its own application model. PySpur's docker-compose.yml shows a self-hosted shape: a backend image, a postgres:17-alpine service with a pg_isready healthcheck, and named volumes for postgres_data and pyspur_data. That is a straightforward self-hosted stack, and it is the main argument for PySpur over a hosted alternative if your data cannot leave your network.

None of this makes PySpur a drop-in replacement for any of them. If you already have a working Langflow deployment, the migration cost is real and the README does not describe an import path.

Docker deployment, licensing and what upgrades cost

The repository ships three compose files: docker-compose.yml, docker-compose.dev.yml and docker-compose.staging.yml. The production compose file pulls ghcr.io/${GITHUB_REPOSITORY:-pyspur-dev/pyspur}-backend:${VERSION:-latest}, which means the image tag is controlled by the VERSION variable in .env and defaults to latest. Pinning VERSION to a specific tag is the only version-control lever the compose file exposes, and the .env.example sets VERSION=latest by default. Anyone deploying this should change that value, because latest plus an automatic pull is how you get an unplanned upgrade.

The image name also depends on GITHUB_REPOSITORY, set to pyspur-dev/pyspur in .env.example. If you fork the repository, that variable has to point at your fork or you will pull the upstream image.

Licensing is Apache-2.0, which permits commercial use and modification and requires that you preserve notices and state changes. That is a permissive licence, but the repository includes an nginx/ directory and frontend assets, so if you redistribute a modified build, check which files carry notices. This is not legal advice; read the LICENSE file and the Apache-2.0 text before shipping a modified version.

Upgrade cost is the weak spot. The last release listed is v0.1.18 from 2025-03-25, while the last push to the default branch was 2026-06-29. That gap between tagged releases and branch activity means the release notes may not describe what is on main. If you deploy from main rather than a tag, you are tracking unreleased code.

Editorial conclusion

Adopt PySpur if you are an AI engineer who already writes Python agents and wants a UI for tracing, evals and human approval steps without leaving the language. Skip it if you need Windows development support or a documented rollback path, since the README states Windows/PC development is not supported and the README does not document rollback. Before committing, verify that your PostgreSQL connection works from the .env file, that your chosen provider key is accepted in the API Keys tab, and that a human-in-the-loop breakpoint actually pauses and resumes on your own workflow.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. PySpur-Dev/pyspur on GitHub
4. README
5. Releases