Vera

A capability runtime for building, operating, and improving AI systems

Vera turns ordinary Python functions into distributed, observable tools that agents, people, APIs, workflows, and external MCP clients can all use. One @capability decorator connects a function to the registry, HTTP, MCP, the interactive harness, event streams, workers, and Vera's planning engines.

That simple centre supports a much larger system: local and hosted models, agentic loops, DAG workflows, semantic memory, a polyglot data fabric, browser operation, remote development, hardware nodes, and Loop Lab—Vera's isolated, reviewed self-improvement workflow.

[!NOTE] Vera is an ambitious, actively developed system. The core runtime is usable, but some integrations and studios are experimental. Issues, focused pull requests, documentation improvements, and reproducible bug reports are very welcome.

Why Vera is different

A Vera capability is simultaneously:

• a Python function callable in-process;
• an HTTP endpoint with a generated schema;
• an MCP tool for Claude, Codex, and other clients;
• a distributed job that can run on a worker;
• a building block for DAGs and agentic loops;
• an observable event source with trace and provenance data; and
• an interactive action in Vera's web harness.

There is one registry and one execution contract. A tool does not need separate implementations for the UI, API, agent runtime, and worker cluster.

A capability is more than a remotely callable function. Its registered name is a stable operation identity; its JSON schema tells callers how to supply data; its Capability Contract describes the task it fulfils, effects it may cause, resources and authority it needs, lifecycle, and operational expectations. The same wrapper then applies tracing, policy observation or enforcement, activity recording, error normalization, optional caching, and local or worker dispatch. This lets a model choose between several implementations of the same task using machine-readable evidence instead of guessing from similar names.

Registration does not itself grant authority. A capability can be discoverable while policy still denies a particular call, and inspection capabilities can describe plans, contracts, runtime mappings, or health without executing the thing they describe. This separation—describe, resolve, authorize, execute, observe—is what allows Vera to interoperate with external MCP servers and agent or workflow runtimes without absorbing each one into a new bespoke loop.

The capability is therefore Vera's unit of interoperability, not merely its RPC format. A complete capability has five independently inspectable layers:

Those layers deliberately do not collapse into one score. Discovery does not authorize execution; a provider's advertised tool does not become trusted because it was found; and telemetry can inform selection without rewriting the declared contract. Native Python, workers, MCP tools, model providers, workflow engines, and remote agents can therefore share a control path while each runtime retains authority over its own execution state.

What you can build

Architecture in one minute

 People · Agents · MCP clients · REST clients · Scheduled programs
                              │
                    ┌─────────▼─────────┐
                    │ Capability registry│
                    │ schema · policy   │
                    │ events · tracing  │
                    └─────────┬─────────┘
                              │
       ┌──────────────┬───────┼────────┬───────────────┐
       ▼              ▼       ▼        ▼               ▼
   LLM routing    DAG/loops  Workers  Operator     UI panels
       │              │       │        │               │
       └──────────────┴───────┼────────┴───────────────┘
                              ▼
        Redis · Postgres · Chroma/FAISS · Neo4j · object storage

Vera starts the orchestrator first and connects optional backends lazily. Unavailable integrations degrade the capabilities that need them rather than preventing the entire registry from starting.

Before you install

Vera's resource needs depend much more on model size and concurrency than on the web orchestrator itself. Do not use the old blanket RAM figures as a capacity promise.

These are planning baselines, not hard limits. Model weights, quantization, context length, parallel requests, vector collections, logs, and retained artifacts all change the answer. Read the performance and sizing guide before choosing hardware or defining an SLO.

Quick start

The supported starting path is the Docker stack:

git clone https://github.com/BoeJaker/Vera.git
cd Vera
cp .env.example .env
make secret
make up
make logs

Without make:

# Linux / macOS
./build.sh up

# Windows PowerShell
.\build.ps1 up

Then open:

• Harness: http://localhost:8999/
• OpenAPI: http://localhost:8999/docs
• Health: http://localhost:8999/health
• MCP catalog: http://localhost:8999/mcp/tools

For native installation, verification, and troubleshooting, follow Getting started.

Your first capability

from Vera.vera.capability_orchestration import capability


@capability(
    "example.greet",
    description="Return a friendly greeting.",
    http_method="POST",
    http_path="/example/greet",
    http_tags=["example"],
)
async def greet(name: str, trace_id=None):
    return {"message": f"Hello, {name}!"}

After the module is loaded, example.greet is discoverable through MCP, callable through the registry and HTTP route, visible to planners, and represented by its input schema in the harness.

For production-facing tools, also declare a v2 contract with a canonical task, effects, output schema, policy posture, owner, and resource class. Legacy capabilities continue to work, but unknown declarations remain visible as migration gaps and are not silently interpreted as safe defaults.

curl http://localhost:8999/mcp/call \
  -H 'content-type: application/json' \
  -d '{"name":"example.greet","arguments":{"name":"Vera"}}'

See Capability framework for modes, streams, caching, memory, worker dispatch, errors, and UI registration.

Explore by goal

Performance is a runtime property

Vera monitors the system it is actually running on rather than pretending one hardware list guarantees performance. The Performance Monitor covers:

• event-loop stalls and blocking-call stack traces;
• CPU and memory pressure;
• Ollama health, availability, and saturation;
• stale Redis consumers and zombie jobs;
• rotating logs and an in-memory tail; and
• advisory or strict performance gates during Loop Lab promotion.

The default gate fails on any critical finding, warns above four warnings, and blocks promotion only when VERA_PERF_GATE_STRICT=1. A loop stall of 3 seconds or more is critical; shorter recent stalls are warnings. Full semantics and measurement guidance are in Performance and sizing.

Repository map

vera/
├── capability_orchestration.py   core registry, HTTP/MCP surface, lifecycle
├── config.py                     backend and runtime configuration
├── dag/                          DAGs, loops, profiles, authoring
├── workers/                      distributed work and model routing
├── fabric/                       ingestion, vectors, graphs, SQL, objects
├── operator/                     browser operation and documentation capture
├── evolve/                       Loop Lab, sandboxes, review, promotion
├── monitor/                      performance diagnostics and gates
├── agents/ · chat/ · research/   agent-facing applications
├── ide/ · execution/             development and remote execution
└── mesh/ · render/ · media/      edge, documents, images, and audio

The documentation hub maps the remaining packages and studios.

Project status and contribution

Vera changes quickly. Before submitting a change:

1. open an issue or describe the problem and expected behavior;
2. keep the change focused and add deterministic tests;
3. update the relevant guide when behavior or configuration changes;
4. never commit credentials, generated secrets, or local environment files; and
5. use Vera's isolated development workflow for Vera repository changes.

The canonical development and release workflow is documented in Loop Lab.

License

This repository does not currently include a license file. Contact the project maintainer before assuming rights beyond viewing or evaluating the source.