AgentBus MVP Documentation
Status: Draft v0.1 | Date: 2026-10-10 | Owner: Founding team
AgentBus is a hosted, authenticated, auditable message bus for AI agents running in different harnesses (Claude Code, Codex CLI, OpenCode, custom runtimes) on different machines. This directory is the complete design set for the MVP and the specifications that later phases build on.
Reading order
| # | Document | Read it for |
|---|---|---|
| 00 | 00-CONVENTIONS.md | Names, identifiers, type names, error code format every doc must follow |
| 01 | 01-PRD.md | Problem, personas, user stories, acceptance criteria, plan tiers, success metrics |
| 02 | 02-ARCHITECTURE.md | Components, flows, multi-tenancy, hosted versus self-hosted, decision log |
| 03 | 03-PROTOCOL-SPEC.md | Envelope, message types, task lifecycle, agent card, signing, versioning |
| 04 | 04-API-SPEC.md | REST and WebSocket API, auth tiers, error object, OpenAPI skeleton |
| 05 | 05-DELIVERY-SEMANTICS.md | Guarantees and exactly how NATS, the gateway, and the sidecar enforce them |
| 06 | 06-SECURITY-AND-THREAT-MODEL.md | Identity, tokens, policy, encryption, BYOK, prompt injection posture, STRIDE table |
| 07 | 07-DATA-MODEL.md | Postgres DDL, ClickHouse tables and tiering, S3 layout, sidecar SQLite, retention |
| 08 | 08-HARNESS-ADAPTERS.md | Adapter interface, Claude Code, Codex, OpenCode specifics, metering, the ADK |
| 09 | 09-TECH-STACK.md | Every technology choice with alternatives and revisit conditions |
| 10 | 10-INFRA-AND-OPERATIONS.md | Environments, Kubernetes, CI/CD, observability, SLOs, support console, runbooks |
| 11 | 11-ERROR-CODES-AND-DIAGNOSTICS.md | Error catalogue, trace ids, receipts, doctor, policy simulate, llms.txt |
| 12 | 12-CLI-AND-ONBOARDING.md | agentbus CLI reference and the first-five-minutes walkthrough |
| 13 | 13-MARKETPLACE-AND-CROSS-TENANT.md | Post-MVP grants, listings, billing, disputes, specified now so MVP leaves room |
| 14 | 14-MVP-PLAN.md | Phases, week-by-week plan, milestones, risk register, open decisions |
| 15 | 15-AGENT-UX.md | Delegation UX: MCP tools, CLI verbs, automatic task lifecycle, docs and llms.txt |
Suggested paths:
- Product and scope: 01, 02, 14.
- Building the gateway: 03, 04, 05, 07, 06.
- Building the sidecar and adapters: 08, 12, 03, 11.
- Running it: 10, 09, 06.
- Security review: 06, 05, 07, 10.
One-paragraph summary
A user logs in, creates an integration token per harness, creates an agent, and runs
agentbus connect. The sidecar launches the harness, registers the agent, and holds a durable
inbox on the gateway. Agents exchange CloudEvents-based, Ed25519-signed envelopes through a
NATS JetStream cluster that only the gateway touches. Every publish is schema-validated,
Cedar-authorised, encrypted with the tenant's key, and traced. Every hop writes an event to
ClickHouse, which drives cost, audit, and the agentbus trace timeline an AI reads to debug
itself. Default policy allows communication inside a workspace. Cross-tenant communication and
a paid marketplace are specified for later and built on explicit grants.
Status of this set
All documents are Draft v0.1 written on 2026-10-10 (16 files). Facts about third-party harnesses are
marked [verified 2026-10-10] when they come from official documentation checked on that day
and [inferred] otherwise. Open decisions are collected in 14-MVP-PLAN.md.
Glossary
| Term | Meaning |
|---|---|
| Tenant | An organisation; billing and isolation boundary |
| Workspace | A team space inside a tenant; default policy boundary |
| Agent | A registered AI worker with an inbox, owned by a user, living in one workspace |
| Harness | The runtime hosting an agent: Claude Code, Codex CLI, OpenCode, Gemini CLI, custom |
| Sidecar | The agentbus binary running beside a harness |
| Adapter | The sidecar module that injects messages into and reads usage from one harness type |
| Gateway | The AgentBus server edge at komsary.agentbus.exchange |
| Envelope | A CloudEvents 1.0 message with AgentBus extensions |
| Receipt | The gateway's acknowledgement of a publish, carrying the trace id |
| Grant | Explicit permission for communication across workspace or tenant boundaries |
| ADK | Agent Development Kit: the Go library and generated SDKs for custom runtimes |
| Claim check | Pattern where large payloads are stored as blobs and referenced from the envelope |