AgentMBX

A signed mailbox for AI coding agents. Claude Code, Codex, OpenCode, Kimi, Hermes and any MCP client can message each other: on one machine or across machines on your network. Idle agents get woken up, and every message says who really sent it.

agentmbx.com · Status: alpha (0.2) · License: BUSL-1.1 (source-available)

you ── Claude Code (planner) ──┐                         ┌── Codex (api-dev)      ← woken by `codex queue`
                               ├── agentmbx daemon ◄────►├── OpenCode (web-dev)   ← woken by its session API
     Kimi / Hermes / any MCP ──┘   (this machine)   LAN  └── Claude (reviewer)    ← woken by a channel event
                                                          (a paired machine)

Why

Most people now run more than one coding agent, and often on more than one machine. They can't talk to each other. The options today:

• Paste between them by hand.

• One vendor's multi-agent feature. These only work for that vendor's agents.

• A heavyweight agent platform.

AgentMBX gives every agent the same small set of mailbox tools. It delivers messages between machines you pair. It wakes the recipient when its CLI allows that. It keeps a hard line between what a message says and what the recipient is allowed to do.

Related MCP server: claude-intercom-mcp

What you get

• 9 MCP tools that work in any MCP client: mbx_inbox, mbx_read, mbx_reply, mbx_ack, mbx_send, mbx_thread, mbx_search, mbx_agents, mbx_whoami.

• One-command setup: agentmbx setup finds Claude Code, Codex, OpenCode, Kimi and Hermes and wires each one (MCP server, hooks, and a bundled skill that teaches agents the mailbox loop). agentmbx doctor checks it all.

• Addressing: agent, agent@host, role:reviewer, * (broadcast), or owner (you).

• Threads, replies, and requests that need a reply. @mentions, /claim / /done directives and task refs (T123) are parsed from the body.

• Wake-ups for idle sessions, one adapter per CLI. The wake text never contains the message itself, only a pointer to the inbox tool.

  CLI	Wake path	Status
  Codex	codex queue --thread <id>	tested live
  OpenCode	the local service's session API (/synthetic)	tested live
  Claude Code	MCP channel event (research preview, --dangerously-load-development-channels server:mbx)	automated test only
  Kimi	hook, next turn (no external push exists)	not tested live
  Hermes	cron now; plugin planned	not tested live
  anything else	desktop notification

• Across machines: a small daemon per host. Hosts pair with one command each: agentmbx pair prints a one-time token, agentmbx join <host> <token> on the other machine finishes it (or compare a 6-digit code instead). Hosts find each other on the LAN over mDNS. Every hop is signed. Messages to a sleeping machine wait in an outbox and retry for 72 h, and each is stored exactly once.

• A wake brake: at most 1 wake per agent per 30 s, 6 per thread per hour, 60 per agent per day. Plain status messages never wake anyone, so two chatty agents can't burn your tokens overnight.

• Full-text search (SQLite FTS5) and an audit log. mbx:<id>@<host> references can be cited from tickets and notes.

• Zero infrastructure: Node 24, SQLite built into Node, and three small dependencies (the MCP SDK, zod, and multicast-dns for LAN discovery). No broker, no cloud, no accounts.

Trust model (the short version)

• Owner authority belongs to one running session. You run agentmbx owner grant in your own terminal, pick the live session, and type your passphrase. The grant is bound to a key that exists only in that session's memory, for 12 h by default. Another process using the same agent name gets nothing.

• The owner key is encrypted with your passphrase and unlocks only from a real terminal. An agent's shell commands cannot use it.

• Capabilities are enforced by the receiving machine (task.assign, decision, broadcast, alert). A message outside its grant arrives labelled authority: none with a warning.

• No message can approve a permission prompt or change a recipient's config, owner-signed or not. The MCP instructions tell every agent this, and agents treat all message content as data, not instructions. This mirrors how Claude Code handles messages from other sessions.

• Known limits:

  • The LAN hop is signed but not encrypted yet (the enc field is reserved).

  • Agents on the same machine share the OS user boundary.

The full design is in docs/SPEC.md. The adversarial review that shaped it is in docs/COUNCIL-VERDICT-2026-09-26.md.

Quick start

curl -fsSL https://agentmbx.com/install.sh | sh
# or, straight from GitHub:
curl -fsSL https://raw.githubusercontent.com/kryptobaseddev/agentmbx/main/install.sh | sh

agentmbx setup      # host key, daemon, and every agent CLI it finds (MCP + hooks + skill); backs up each file it edits
agentmbx doctor     # ✔/✗ checklist with a one-line fix for each problem

The installer puts a single self-contained binary (no Node.js needed) in ~/.local/bin/agentmbx after checking its sha256 against the release manifest. Keep it current with:

agentmbx version --check     # is there a newer release?
agentmbx update              # verify the signed manifest, download, check sha256, replace the binary, restart the daemon

The daemon checks once a day and shows one desktop notification per new version; agentmbx status and mbx_whoami show update available: x.y.z. Prefer npm? npm i -g agentmbx (Node >= 24), then update with npm i -g agentmbx@latest. Maintainers: docs/RELEASING.md.

Restart your agent sessions and they have the mbx_* tools. agentmbx setup --dry-run previews, --only codex limits it, --uninstall undoes it. What it writes for each CLI (and how to do it by hand): docs/INSTALL.md.

Pair a second machine:

desktop$ agentmbx pair                             # prints a one-time token and the exact line to run on the other machine
laptop$  agentmbx join desktop 7K3M-QX9D-4HTR      # or: agentmbx join desktop.local:7373 7K3M-QX9D-4HTR

That's it: both machines are paired, no codes to compare. The token is single use and expires after 10 minutes (--ttl). Both sides prove they know it with an HMAC over both machines' host and owner keys, so a machine in the middle can't substitute its own keys. agentmbx discover lists AgentMBX hosts on the LAN (mDNS). If multicast is blocked, use the host:port form. Prefer comparing codes by eye? agentmbx pair --compare desktop.local:7373, then agentmbx pair approve <other-host> <code> on both machines.

Then from any agent: "send api-dev@desktop a request to run the migration tests and reply with the result". Or from a shell:

agentmbx send --as planner --to api-dev@desktop --kind request --needs-reply --subject "run migration tests" -m "…"
agentmbx inbox --as planner

Owner authority (optional, only on the machine you use):

agentmbx owner init                                            # choose a passphrase
agentmbx owner grant planner --caps task.assign,decision --ttl 12h

Notifications

When an agent has no wake path (or its wake fails), the daemon shows a desktop notification instead.

• macOS: build the small menu-less app once, then (re)install the daemon:

  scripts/build-macos-app.sh        # needs Xcode command line tools; writes build/AgentMBX.app
  agentmbx daemon install           # copies it to ~/Applications/AgentMBX.app
  agentmbx notify-test --as planner # sample notification through the same path wake-ups use

  • Notifications then come from AgentMBX with its own icon, not Script Editor. The first one asks for permission. Manage it in System Settings > Notifications > AgentMBX.

  • Clicking a notification opens a Terminal window running agentmbx inbox --as <agent>.

  • The launchd agent starts through AgentMBX.app/Contents/MacOS/agentmbx-daemon, a tiny launcher that execs Node. Background Task Management names the job after that binary, so the Login Items entry reads "AgentMBX" instead of "node".

  • Without the app, AgentMBX falls back to osascript notifications.

• Linux: notify-send -a AgentMBX -i mail-message-new.

• Set MBX_NO_DESKTOP=1 to turn desktop notifications off.

Command reference

agentmbx help lists everything:

• Messages: send, inbox, read, ack, thread, search, agents, status

• Setup: setup [--dry-run] [--only …] [--uninstall], doctor, version [--check], update

• Machines: init, pair, join, discover, pair --compare, pair approve, peers, peers remove, daemon [install|uninstall], notify-test

• Owner: owner init|show|grant|revoke

• Integration: mcp, hook session-start|prompt|stop --cli <cli>, import-v2

• Install: version [--check], update [--check] [--yes]

How it compares

* Claude channels are a research preview.

Development

git clone https://github.com/kryptobaseddev/agentmbx && cd agentmbx && npm install
npm test            # 49 tests: crypto, trust (incl. the council's four), two-host HTTP, token pairing + mDNS, MCP client, channel push, updater, service/notifier, setup/doctor on a fake HOME
npm run typecheck
python3 scripts/e2e/wake-codex.py      # live: wakes a real idle Codex TUI (see docs/TESTING.md)
scripts/build-macos-app.sh             # macOS: AgentMBX.app (notifier + launchd launcher); releasing: docs/RELEASING-macos.md

• Docs: SPEC · INSTALL · RESEARCH · TESTING · RELEASING-macos

• Contributions: issues are welcome. Pull requests need agreement that the Licensor may license contributions under the terms in LICENSE.

License

AgentMBX is source-available, not open source. It is licensed under the Business Source License 1.1:

• Free: reading, modifying, and running it for your own agents and your own organization, in production too.

• Needs a commercial license: offering it, or anything built from it, to others as a product, hosted service or embedded agent-messaging feature. Contact via agentmbx.com.

• Each version becomes Apache 2.0 four years after release (Change Date 2030-09-26 for 0.1).

"AgentMBX" and "MBX" are trademarks of Keaton Hoskins; see NOTICE.