Home / agent-bus
Connect AI agents, scripts, people and services — on one machine or across many — so they can find and message each other safely.
One Go daemon is the registry and the broker; the CLI, the MCP face for Claude Code, Codex and OpenCode, and the TypeScript web face are its doors.
MVP is released — the current release, on the 0.8 line (changelog). Source and docs: github.com/parf/ai-agent-bus.
Why agent-bus
AI sessions, scripts and services need to reach each other — across machines, by name, with a say over who may call whom. The usual answer is a broker, a database and an auth server. agent-bus is one daemon.
Simple to run
- One daemon, no broker
- One Go binary and one SQLite file.
- Any number of hosts
- Over HTTP, HTTPS or a forwarded socket.
- One-command install
- A verified setup; an upgrade that rolls back on failure.
- You can tell what runs
- Every program and
psline shows its version.
Made for agents
- AI-native
- Live Claude Code, Codex and OpenCode sessions get messages pushed in.
- MCP tools
- AI CLI tools see agents, services, queues and topics over MCP, and can list, send, consume and reply.
- Any script is an agent
agent-bus startserves it under a name, through restarts.- Tested by breaking it
- Every check has been seen to fail first.
Web management panel
- Overview — what needs attention (refusals, full queues, lost messages), then live counters per kind.
- A page per kind — Agents, Services, Queues, PubSub, Users, Groups: search, filters, details.
- Management — register records, edit ACLs and group members, manage users, transfer or retire.
- Activity graphs — by day, week and month, per record or node-wide, 400 days back with ‹ Prev.
- Diagnostics — refusals by reason and stray names, refreshed on demand; message bodies never shown.
- Isolated — its own process and
nobody-like account,agent-bus-web; holds no bus state.
Safe by design
- Every call is someone
- Its own credential, and the ACL checked before delivery.
- No token files for local users
- Your Unix socket is your credential.
- Names say what they are
alice@teama User,#worker@teaman Agent,@opsa Group.- Users own everything
- An Agent never owns what it creates.
- Least privilege
- Separate accounts, hardened units, no secrets in logs.
- Durable where it matters
- Administrative writes commit before they are answered.
Concepts
Record kinds
Everything on the bus is a named
record
of one of six kinds. An optional realm (@team) is part of the name.
- 👤 User
- A person, and the inbox they read:
aliceoralice@team. - 👥 Group
- A named list of actors for ACLs; can have owners, maintainers and secrets.
- 👾 Agent
- An AI session or a script, and the inbox it reads; its name begins with
#. - 📮 Queue
- A shared inbox that hands each message to one competing reader.
- 📣 PubSub
- Keeps nothing; copies each publication to everyone on its Deliver-To list.
- 📡 Service
- A card for something outside the bus: address, protocol and a secret only its allow list reads.
Records and access
- Owner
- The User a record belongs to; may transfer it and names its Maintainers.
- Maintainers
- Users or Agents the Owner lets edit a record's description, ACL and status.
- ACL
- Who may reach a record: Users, Agents, Groups (nested), or
*for every registered user. - Personal
- A record meant only for its Owner and that Owner's Agents.
- Private values
- An Agent, Service or Group may carry a configuration and a secret; everyone else sees only a digest.
- Active / Inactive
- Turns any record on or off — a user, agent, group or service. An inactive one is hidden and refused; its name is kept.
Messaging
- Inbox
- A User, an Agent and a queue each hold one; a message waits there until a reader takes it.
- Forwarding
- An agent or queue may pass what it receives on to one destination, which must allow it.
- Request and reply
- Replies are ordinary messages matched by topic and tag; the daemon keeps no conversation state.
- Receipts and deadlines
- A reader may confirm it took or finished a message, and a caller may say when an answer stops being useful.
- One reader per inbox
- A message is taken at most once; readers that say so may share an inbox as a pool.
- TTL, bound and overflow
- How long an inbox keeps a message, how many it holds, and whether a full one refuses or drops the oldest.
Faces and logs
- Faces
- The
agent-busCLI; the MCP face and its launchers; the foreground runner, which puts a script behind an agent name, optionally sandboxed; and the web face. - Web face
- Its own process and hardened unit: overview, every record and person, activity history by day, week and month, and diagnostics, with bodies never shown.
- Logs
- An audit log of every administrative action, an error log copied to syslog, and an on-demand debug log.
The constitution is the model in one page; the glossary names everything.
Using it
New here? The user guide is the shortest path from nothing to a running agent. Installing is setup; building from source is source instructions.
CLI example
On a configured bus, with permission to register these names:
agent-bus register mysql-prod@srv1 --addr host:3306 --protocol mysql
agent-bus channel create alerts.prod@srv1 --kind pubsub
agent-bus channel create build-jobs@srv1 --kind queue --ttl 1h --bound 1000
agent-bus manage alerts.prod@srv1 --add-to-set-allow '@ops'
agent-bus ls --all
agent-bus publish --channel alerts.prod@srv1 "disk nearly full"
agent-bus send '#worker@srv1' "an agent's name begins with #"The daemon is trusted with message bodies (trust boundary), and a crash may lose queue traffic since the last checkpoint (durability).
Plans
| Release | Status |
|---|---|
| R0.8 (MVP) | Released, current (0.8) |
| R1 | Proposed: distributed identity and managed services |
| R1.1 | Proposed tools stage |
| R1.2 | Unscheduled exploration after tools |
| R2.0 | Undecided or unassigned ideas |