AGENT-33

Local-First Multi-Agent Orchestration Platform

Governance · Evidence · Workflows · Multi-tenant Isolation · Observability

Local-First · Approval-gated automation · Audit trail by design · Multi-tenant

Quick Start · Architecture · API Reference · Onboarding

Use Cases · Walkthroughs · Self-Improvement · Operator Runbooks

</div>

At a Glance

<table> <tr> <td align="center" width="16%"> AGENTS 6 Reference agent definitions </td> <td align="center" width="16%"> WORKFLOWS DAG Composable, with retries </td> <td align="center" width="16%"> TOOLS 7 Schema-validated builtins </td> <td align="center" width="16%"> SUBSYSTEMS 20+ Lifespan-wired services </td> <td align="center" width="16%"> LLM PROVIDERS 20+ Auto-registered from env </td> <td align="center" width="16%"> TENANCY Native Multi-tenant by design </td> </tr> </table>

Why AGENT-33

AGENT-33 is a local-first AI agent orchestration platform for teams that want real workflows, explicit governance, and a usable control plane instead of a pile of disconnected scripts. It combines an API runtime, workflow engine, memory stack, review/release controls, and a first-party frontend so you can run guarded automation from one system.

Local-first runtime — FastAPI backend, Docker Compose bootstrap, Ollama-friendly model routing
Contained Agent OS — optional Linux operator workspace with first-party tools, state, and stack connectivity
Guardrailed automation — scopes, approvals, autonomy budgets, and review/release workflows
Agent + workflow orchestration — invoke agents directly or compose repeatable DAG workflows
Operational visibility — health, dashboard surfaces, traces, evaluations, and rollout telemetry
Extensible platform — packs, tools, memory, webhook intake, and improvement loops

flowchart LR
    U[Operator / Client] -->|HTTP · WebSocket · SSE| API[FastAPI Surface]
    API --> AR[Agent Runtime]
    AR --> WF[Workflow Engine<br/>DAG · retries · checkpoints]
    AR --> SK[Skill Registry<br/>L0 / L1 / L2 disclosure]
    AR --> TG[Tool Governance<br/>allowlist · autonomy · approvals]
    AR --> MEM[(Memory<br/>pgvector + BM25 RRF)]
    WF --> TP[Trace Pipeline<br/>failure taxonomy · retention]
    TG --> TP
    AR --> TP

    style API fill:#0ea5e9,color:#fff
    style AR fill:#10b981,color:#fff
    style TG fill:#ef4444,color:#fff
    style TP fill:#f59e0b,color:#fff
    style MEM fill:#8b5cf6,color:#fff

For the full lifespan startup order, runtime modes (lite, standard, enterprise), and middleware chain, see docs/architecture/overview.md.

Repository Layout

engine/ — FastAPI runtime, orchestration services, API routes, tests, Docker Compose stack
frontend/ — AGENT-33 control plane UI served at http://localhost:3000
core/ — orchestration specs, policy packs, protocol references, workflow materials
docs/ — canonical operator, setup, onboarding, and release-readiness documentation

Quick Start

30-Second Try

Spin up the stack and confirm it's alive in under a minute:

cd engine && docker compose up -d
curl http://localhost:8000/health

Then continue below for the full operator setup (JWT minting, agent invocation, control plane).

Full Operator Setup

Prerequisites

Docker Desktop or Docker Engine with Compose
Python 3.11+
curl
Ollama reachable from the stack (http://host.docker.internal:11434 by default), or use the bundled/local override paths documented in the setup guides

1. Start the stack

cd engine
cp .env.example .env
docker compose up -d
curl http://localhost:8000/health

If you reuse an Ollama container from another Compose project:

docker compose -f docker-compose.yml -f docker-compose.shared-ollama.yml up -d

2. Open the control plane

Frontend: http://localhost:3000
API docs: http://localhost:8000/docs

Default local credentials from .env.example:

username: admin
password: admin

3. Mint a local JWT for API access

docker compose exec -T api python -c "import os,time,jwt; now=int(time.time()); payload={'sub':'local-admin','scopes':['admin','agents:read','agents:write','agents:invoke','workflows:read','workflows:write','workflows:execute','tools:execute'],'iat':now,'exp':now+3600}; print(jwt.encode(payload, os.getenv('JWT_SECRET','change-me-in-production'), algorithm=os.getenv('JWT_ALGORITHM','HS256')))"

Set the token in your shell:

export TOKEN="<paste-token-here>"

PowerShell:

$env:TOKEN = "<paste-token-here>"

4. Verify the first agent flow

List agents:

curl http://localhost:8000/v1/agents/ \
  -H "Authorization: Bearer $TOKEN"

Invoke the orchestrator:

curl -X POST http://localhost:8000/v1/agents/orchestrator/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "task": "Create a short rollout plan for adding cache metrics"
    },
    "model": "llama3.2",
    "temperature": 0.2
  }'

First 5-Minute Operator Path

Start the stack and confirm /health
Sign in to http://localhost:3000
Mint a local JWT or use the UI token flow
List agents with GET /v1/agents/
Invoke an agent or execute a minimal workflow
Explore the dashboard, traces, reviews, evaluations, and autonomy surfaces from the UI

For a fuller beginner path, use:

Security and Production Warning

Bootstrap auth is for local development only. Do not expose AGENT-33 publicly with default credentials or default secrets.

Before any shared, VPS, or production deployment:

set AUTH_BOOTSTRAP_ENABLED=false
rotate API_SECRET_KEY
rotate JWT_SECRET
rotate ENCRYPTION_KEY
review SECURITY.md
work through the Release Checklist

Documentation Map

Start here

Deep references

Who this is for

Operators who need a guarded local or self-hosted AI control plane
Platform teams building approval-aware automation and workflow execution
Engineering teams running review, release, evaluation, and autonomy gates in one runtime
Researchers and builders experimenting with packs, memory, training, and improvement loops

Roadmap

AGENT-33 is under active development. Near-term public direction:

Ecosystem growth — broader pack catalog, community-contributed skills and tools, signed pack distribution
MCP integrations — richer hosted MCP server surface and tighter MCP client interop with the agent runtime
Public benchmarking — continued evaluation against SkillsBench with CTRF reporting and weekly full-tier runs
Provider depth — first-class support for additional local-inference backends (llama.cpp, LM Studio, AirLLM) and embedding providers
Operator UX — visual workflow builder polish, sub-agent execution trees, knowledge ingestion cron expansion

See CHANGELOG.md for release history.

Contributors

Every commit, issue, review, and Discussion thread makes the project better. Thank you.

Star History

License

Apache License 2.0. See LICENSE.

Documentation · API Reference · Architecture · Changelog · Presentation Suite · Discussions

AGENT-33 v2.1.0 · Apache License 2.0 · Local-first multi-agent orchestration with built-in governance