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 ps line 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 start serves 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@team a User, #worker@team an Agent, @ops a 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: alice or alice@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-bus CLI; 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).

Integrations

Tools built for agent-bus — suggested ways to put it to work.

mdhouse — chat with an agent about a document

mdhouse is a local, git-aware Markdown workspace. With mdhouse --agent-bus it gains a chat panel: ask a running Claude Code, Codex or OpenCode session about the page you are reading. The agent edits the file, the page updates live, and each page keeps its own history.

No adapter on the agent side: the panel sends ordinary bus messages and the agent replies as to any peer. Works with a local or a remote bus — mdhouse Agent Bus integration.

Plans

License

PolyForm Noncommercial.