Veldra: a self-hosted agent harness where an agent is a versioned AgentSpec row

The problem Veldra targets: agent definitions that live in code

Most agent frameworks ask you to write the agent. You define tools in Python decorators, hard-code a system prompt, wire retrieval by hand, and redeploy whenever the prompt or tool list changes. Veldra inverts that. The README states the load-bearing idea directly: "an agent is data, not code, a versioned AgentSpec row in Postgres." Building an agent means compiling natural language into a validated AgentSpec. Changing it means applying a JSON-Patch that you approve. The runtime is described as a pure interpreter of that spec.

The audience is narrow and specific. You need to be comfortable running Postgres with pgvector, Redis, MinIO, and a FastAPI process, and you need to want the agent definition to be inspectable and versioned rather than buried in a repository. Teams that want a hosted chatbot builder are not the target. Teams that have already been burned by prompt changes that cannot be diffed or rolled back are.

How the AgentSpec compile-and-interpret loop actually works

The architecture diagram in the README shows one FastAPI process covering the edge, the orchestrator, the runtime, and RAG, plus a Vue 3 SPA that talks to it over REST and SSE with a bearer token. The orchestrator does two jobs: turning natural language into an AgentSpec, and routing an incoming task to an existing agent when one already fits.

Storage is split between a stable `agents` row and an append-only stack of immutable `AgentSpec` versions. That append-only design is the part worth paying attention to. It means an edit is a new row, not a mutation, so the JSON-Patch approval step has something concrete to apply against and the previous behaviour stays on disk. The runtime reads the current version and interprets it: which built-in or plugin tools are granted, which knowledge base to search, which thinking method to use, and whether the agent delegates to sub-agents.

Tools come from two places. Built-ins are always available and the README lists `kb.search`, `calc.eval`, `web.scrape`, `http.fetch`, `time.now`, `fs.*`, `json.query`, and `regex.extract`. External tools arrive as MCP connectors over stdio, Streamable HTTP, or SSE, installed from a template gallery with credentials configured and the connection tested before it is enabled per agent. The README notes that side-effecting connector tools require explicit approval, which is the right default for anything that writes to Shopify or Alibaba.

Installing Veldra with make quickstart and building a first agent

The README gives a one-command path. Prerequisites are Docker and, for the local-first default, Ollama running on the host. The quickstart target checks prerequisites, pulls the local models, creates `.env` from `example.env`, brings up Postgres with pgvector, Redis, MinIO, and the app, then waits for health.

make quickstart

When it finishes, the app is at http://localhost:8000. The first page is an install wizard that asks you to name the workspace, test the provider connection, and create the admin account. `make down` stops the stack and `make logs` tails the app container.

If you would rather pull the models yourself, the README documents the two Ollama pulls and the compose invocation behind `make up`. Note the model tags exactly as written: the agent model is a 0.8b parameter model, which is small for tool calling.

ollama pull qwen3.5:0.8b
ollama pull nomic-embed-text
make up

For development with hot reload you need `uv` and Node 20.19 or newer on top of the Docker prerequisites. The Makefile copies `example.env` to `.env`, starts only the infrastructure containers, runs migrations, and then prints the two commands to run by hand.

cp example.env .env
make dev
uv run uvicorn veldra_app.main:app --reload
cd apps/web && npm install && npm run dev

The API listens on port 8000 and the UI dev server on 5173, proxying `/api` back to 8000. Once the app is up, describing a task in the composer either routes to an existing agent or builds a new one and drops you into its chat. The CLI offers the same flow for scripted use, and the README says to set `VELDRA_AUTH_ENABLED=false` for local use or supply `VELDRA_SERVICE_TOKEN`.

uv run veldra kb add ./whitepaper.pdf
uv run veldra build "answer from my docs with citations"
uv run veldra ask "what does section 3 say about pricing?"

The example prompt in the README is "answer questions from these docs and always cite the page". Citations are reported to carry `page`, `section`, and `char-span` metadata, so the `ask` output should include those references when retrieval finds a match.

Where Veldra is the wrong tool, and what the README does not settle

The repository badge says MVP, and the release history is empty. If you need a tagged release, a changelog, or a support contract, this is not that yet. The licence is the sharper problem: `pyproject.toml` declares `license = { text = "TBD" }`, so the terms under which you may use, modify, or redistribute Veldra are not stated in the project's own files. That is a blocker for any commercial deployment, not a detail to resolve later. The README does not document a rollback procedure for an approved JSON-Patch either, even though the append-only version stack implies one should exist.

There is a real operational cost hiding in the architecture. Everything is one FastAPI process: edge, orchestrator, runtime, and RAG. That keeps deployment simple, and it also means a heavy ingestion job or a slow LLM call shares a process with the API that serves the UI. The README does not describe worker separation or backpressure. If you plan to index large PDF sets while users are chatting, that is the first thing to load-test.

The learning loop deserves scepticism. The README says that with auto-improve on, an agent stores a lesson from a thumbs-down and also from its own failed tool calls and dead ends, and that lessons plus persona are injected on every future run. Nothing in the README describes how lessons are pruned, ranked, or prevented from contradicting each other over time. An agent that accumulates every past mistake into its context will eventually carry a lot of noise. Treat auto-improve as something to enable deliberately and inspect, not a default you leave running.

Alternatives: LangGraph, CrewAI, and n8n take different positions on where the agent lives

The closest comparison is a code-first orchestration library such as LangGraph, where the agent is a graph you write in Python and version in Git. The difference is where the source of truth sits. In LangGraph your repository is the definition and the deployed process reads it; in Veldra Postgres is the definition and the runtime is an interpreter. Veldra gives you a UI, roles, and an approval step for edits without a redeploy, at the cost of a database dependency for something you could otherwise keep in a file.

CrewAI and similar multi-agent frameworks also let you describe roles and tasks, but the crew is assembled in code at startup. Veldra's orchestrator plans a coordinator plus specialists from a description and wires them through `sub_agents` with depth-capped delegation, then stores the result as a spec you can patch. If you want the team shape to be reviewable data rather than constructor arguments, that matters. If you want deterministic control over exactly which agent runs when, a hand-written graph is easier to reason about than a compiler output.

A visual automation tool like n8n overlaps on the workflow builder. Veldra ships a node set of `start`, `end`, `llm`, `classifier`, `kb_search`, `if_else`, `condition`, `code`, `tool`, `http`, `template`, and `aggregator` with a per-node inspector and typed variable passing. The difference is that n8n's nodes are the product, while Veldra's workflow is one execution mode alongside a native decision loop, and the same AgentSpec model backs all of them.

Maintenance, upgrade cost, and the licence question

The last push to the default branch was on 2026-06-18. The repository is not archived, but there are no tagged releases, so there is no version boundary to pin against and no upgrade notes to read. Upgrading means tracking `main` and reading commits. The Dockerfile applies migrations on every boot with `python -m veldra_app.db migrate` before starting uvicorn, and the comment states this is idempotent and safe on every boot, which removes one manual step but also means a schema change ships the moment you rebuild.

The dependency surface is wide: Anthropic and the MCP SDK for the agent protocol, FastAPI and SSE-Starlette for the edge, SQLAlchemy with asyncpg and Alembic, pgvector and the Qdrant client for two vector store options, Redis, boto3 for S3 or MinIO, pypdf and pdfplumber for ingest, tiktoken, and OpenTelemetry for traces. Each of those moves independently. The `regex` dependency is notable: the pyproject comment says it was chosen as a ReDoS-safe engine with a real per-match timeout for the `regex.extract` tool, which is a deliberate security decision rather than an accident.

On licensing, the only fact available is that `pyproject.toml` sets the license text to TBD. I am not going to guess what that becomes. Until it is filled in, you cannot know whether redistribution or commercial use is permitted, and that uncertainty propagates to anything you build on top. If you are evaluating Veldra for internal experimentation, the licence is a note. If you are evaluating it for a product, it is the first question to answer.

Editorial conclusion

Veldra fits engineers who want to run an agent platform on their own hardware, keep the agent definition in Postgres, and accept MVP software with no tagged releases. Skip it if you need a stable licence, a published release history, or a managed service. Before adopting, read the `license` field in pyproject.toml (currently TBD), confirm which provider example.env points at, and check whether the default 0.8b agent model is strong enough for your tool-calling workload.

Frequently asked questions

Official sources

1. Issues
2. README
3. shamspias/customizable-gpt-chatbot on GitHub