AGENT33 PUBLIC

AGENT-33

Local-First Multi-Agent Orchestration Platform

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

[](LICENSE) [](CHANGELOG.md) [](https://github.com/mattmre/AGENT33-PUBLIC/actions/workflows/ci.yml) [](https://github.com/mattmre/AGENT33-PUBLIC/actions/workflows/security-scan.yml) [](https://www.python.org/) [](https://www.docker.com/) [](https://fastapi.tiangolo.com/) [](https://ollama.com/) [](https://github.com/pgvector/pgvector) [](https://github.com/mattmre/AGENT33-PUBLIC/discussions) [](https://github.com/mattmre/AGENT33-PUBLIC/issues) [](https://github.com/mattmre/AGENT33-PUBLIC/pulls) [](https://github.com/mattmre/AGENT33-PUBLIC/network/members) [](https://github.com/mattmre/AGENT33-PUBLIC/stargazers) [](https://github.com/mattmre/AGENT33-PUBLIC/graphs/contributors) [](CONTRIBUTING.md)

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

[Quick Start](#quick-start)  ·  [Architecture](docs/architecture/overview.md)  ·  [API Reference](docs/api-reference.md)  ·  [Onboarding](docs/ONBOARDING.md)

[Use Cases](docs/use-cases.md)  ·  [Walkthroughs](docs/walkthroughs.md)  ·  [Self-Improvement](docs/self-improvement/README.md)  ·  [Operator Runbooks](docs/operators/)

---

At a Glance

AGENTS 6 Reference agent definitions

WORKFLOWS DAG Composable, with retries

TOOLS 7 Schema-validated builtins

SUBSYSTEMS 20+ Lifespan-wired services

LLM PROVIDERS 20+ Auto-registered from env

TENANCY Native Multi-tenant by design

---

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 EngineDAG · retries · checkpoints]
    AR --> SK[Skill RegistryL0 / L1 / L2 disclosure]
    AR --> TG[Tool Governanceallowlist · autonomy · approvals]
    AR --> MEM[(Memorypgvector + BM25 RRF)]
    WF --> TP[Trace Pipelinefailure 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](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=""

PowerShell:

$env:TOKEN = ""

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

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

For a fuller beginner path, use:

• [Getting Started](docs/getting-started.md)
• [Operator Onboarding](docs/ONBOARDING.md)
• [Walkthroughs](docs/walkthroughs.md)

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](SECURITY.md)
• work through the [Release Checklist](docs/RELEASE_CHECKLIST.md)

Documentation Map

Start here

• [Getting Started](docs/getting-started.md)
• [Operator Onboarding](docs/ONBOARDING.md)
• [Setup Guide](docs/setup-guide.md)
• [Walkthroughs](docs/walkthroughs.md)
• [Use Cases](docs/use-cases.md)
• [Agent OS Runtime](docs/operators/agent-os-runtime.md)
• [API Surface](docs/api-surface.md)
• [Release Checklist](docs/RELEASE_CHECKLIST.md)
• [Documentation Index](docs/README.md)

Deep references

• [Functionality and Workflows](docs/functionality-and-workflows.md)
• [Production Deployment Runbook](docs/operators/production-deployment-runbook.md)
• [Operator Verification Runbook](docs/operators/operator-verification-runbook.md)
• [Horizontal Scaling Architecture](docs/operators/horizontal-scaling-architecture.md)
• [Incident Response Playbooks](docs/operators/incident-response-playbooks.md)

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](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](LICENSE).

---

[Documentation](docs/)  ·  [API Reference](docs/api-reference.md)  ·  [Architecture](ARCHITECTURE.md)  ·  [Changelog](CHANGELOG.md)  ·  [Presentation Suite](presentation/index.html)  ·  Discussions

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mattmre
• Source: mattmre/AGENT33-PUBLIC
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.