agentmbx (AgentMBX) — signed messages between AI coding agents, on this machine and across paired machines
agentmbx setup [--yes] [--dry-run] [--only claude,codex,opencode,kimi,hermes,skill,owner] [--host <name>] [--no-owner] [--policy ask|collaborate|autonomous|yolo] [--uninstall]
init this host, install the daemon, wire every detected agent CLI (MCP + hooks + skill), create the owner key
agentmbx doctor [--fix] checklist: host, daemon, each CLI's wiring, skill, peers, pending pairings, stranded mail (--fix retires phantom mailboxes)
agentmbx claude [claude args…] start Claude Code with the mbx channel, so the idle session wakes when mail arrives
agentmbx send --as <agent> --to <a,b,role:x,*,owner> --subject "…" [-m "body" | --body-file f | stdin]
[--kind message|request|reply|status|decision|alert|task] [--reply-to <id>] [--needs-reply] [--ref path]… [--new-mailbox]
agentmbx replay [--cursor <token>] [--limit 50] [--max-bytes 65536] [--scan-limit 1000]
[--project <id> --project-host <host>] [--topic <tag>] [--thread <id>]
bounded read-only JSON; current provider lease required; bodies are data
agentmbx inbox --as <agent> [--all] [--json] [--needs-reply] [--from <agent>] agentmbx read <id> --as <agent> agentmbx ack <id>… | --all | --thread <id> --as <agent> [--note "…"]
agentmbx whoami --as <agent> [--role r] [--description "…"] inspect/describe the identity leased to this caller
agentmbx thread <id> agentmbx search "<words>" agentmbx agents agentmbx status
Mailbox reads, acknowledgements and replies require this caller’s current MCP lease.
Use --cli <provider> --session <id> when multiple sessions share the caller. --as only selects the held name.
New sends without a lease are marked unverified-sender and grant no delegated authority.
agentmbx status --cli <provider> --session <id> --json current session identity and mailbox counts (read-only)
agentmbx status --cli <provider> [--session <id>] --json --schema mbx.status/v1 HUD snapshot for harnesses; no lease needed (T311)
agentmbx statusline <claude|codex|kimi|opencode|grok|copilot|cursor|gemini> render one MBX segment from the HUD snapshot (T313)
agentmbx identity list [--project <dir>] [--all] [--json] identities with role, holder, claimable and unread (read-only)
agentmbx identity prune [--days 7] [--apply] retire mailboxes older versions generated that nobody holds (dry run by default)
agentmbx identity forward <from> <to> move a mailbox's unread mail to another, with your owner signature
agentmbx identity claim [name] --cli <provider> --session <id> [--wait-ms 5000] [--json]
agentmbx identity release --cli <provider> --session <id> [--wait-ms 5000] [--json]
agentmbx diagnostics --mailbox <name> [--cli <provider> --session <id>] [--limit 20] [--json]
read-only local diagnostics; connector version stays unknown without runtime evidence
agentmbx identity takeover <name> --force --cli <provider> --session <id> replace a holder after owner signature
agentmbx identity result <request-id> [--json] inspect a receipt and finalize expiry; pending means outcome unknown (exit 75)
Machines (pairing: run 'agentmbx pair' on one host, then the 'agentmbx join …' line it prints on the other)
agentmbx init [--host <name>] [--port 7373] agentmbx discover (hosts on the LAN, via mDNS)
agentmbx pair [--ttl 10m] one-time pairing token (single use, default 10 min)
agentmbx join <host|host:port> <TOKEN> pair with the host that printed the token
agentmbx pair --compare <host:port> manual alternative: compare a 6-digit code, then on BOTH hosts
agentmbx pair approve <host> <code>
agentmbx peers agentmbx peers remove <host>
agentmbx peers addr <host> <host:port> move a paired host to a new address (key-checked; usually automatic)
agentmbx host rotate new host and encryption keys, announced to peers (pairings kept)
agentmbx watch [--cli <cli> --session <id>] wait for mail for this session, print the hint and exit (run in the background)
agentmbx wake mute <agent> [--minutes 60] pause wake hints and notices for an agent (mail keeps arriving) agentmbx wake unmute <agent>
agentmbx daemon agentmbx daemon install | uninstall (launchd / systemd user service)
agentmbx relay [serve [--port N]] run an untrusted store-and-forward relay (ADR-035 reference)
agentmbx relay set <url> | relay unset point this daemon at a relay (picked up on daemon start)
agentmbx notify-test [--as <agent>] send a sample desktop notification the way wake-ups do
agentmbx identity export <file> [--force] passphrase-sealed backup (0600) of this host's keys, config and paired peers
agentmbx identity import <file> [--force] restore it on a replacement machine; --force backs up an existing identity first
passphrase from the terminal, or MBX_IDENTITY_PASSPHRASE; a Keychain owner key is not exported
Retention (default off: nothing is deleted until you set it)
agentmbx retention [set <days> | off] the daemon prunes settled mail older than <days> every 6 h
agentmbx prune [--older-than <days>] [--dry-run] delete acked, settled mail older than the window, then VACUUM
never touches unacked mail or the outbox; replay reports pruned history as history_pruned
Owner (each signature needs you: a Touch ID / password prompt on macOS with AgentMBX.app, else the passphrase on a terminal)
agentmbx owner init [--backend keychain|file] agentmbx owner show
agentmbx owner add-device <paired-host> certify a paired machine as yours: it then takes the policies you sign
agentmbx owner grant <agent> [--session <fingerprint>] [--caps task.assign,decision,broadcast,alert] [--ttl 12h]
agentmbx owner revoke <grant-id>
agentmbx owner send --to <agents> --subject "…" -m "…" [--kind task] [--needs-reply] one message signed by you (OWNER)
Policy (what agents may do for each other; each change needs you, like the owner commands)
agentmbx policy set <agent[,agent]|*> <ask|collaborate|autonomous|yolo> [--from local,<host>,principal:<fp>|*] [--host <host,…>|*] [--project <dir>]… [--classes read,edit,outward,permissions] [--ttl 8h]
agentmbx policy list [--json] agentmbx policy renew <id> [--ttl 30d] agentmbx policy revoke <id> | --all (--all is the kill switch, sent to every paired host)
agentmbx lead set <agent> --project <dir> [--ttl 30d] agentmbx lead revoke --project <dir> agentmbx lead show [--project <dir>]
owner-signed project lead: reads every message of that project (mbx_project) and can forward them (mbx_forward)
agentmbx audit [--since 24h] [--json] what agents did on peer requests, YOLO approvals, policy and owner changes
agentmbx version [--check] version, install kind (sea|npm|dev); --check asks the release server
agentmbx update [--check] [--yes] verify the signed release manifest and replace this binary (npm/dev: prints the command)
agentmbx mcp stdio MCP server (add to Claude/Codex/OpenCode/Kimi/Hermes MCP config)
agentmbx hook session-start --cli <codex|kimi|claude|opencode> bind the running session (reads the hook JSON on stdin)
agentmbx hook session-end --cli claude release the exact session on terminal exit (keeps /clear and /resume bindings)
agentmbx hook prompt --cli <…> adds "N unread mbx messages" to the next turn when there is mail
agentmbx hook post-tool --cli claude surfaces new unread mail between tool calls
agentmbx hook permission --cli <claude|codex|kimi> YOLO: approves the prompt only under an active owner policy with the permissions class
agentmbx import-v2 <MAILBOX/v2 dir> import this caller's leased mailbox as unsigned 'legacy' messages
Env: MBX_HOME (default ~/.local/share/agentmbx), MBX_AGENT (agent name for mcp/hooks), MBX_ADVERTISE (host:port others use),
MBX_UPDATE_URL (release download base), MBX_NO_UPDATE_CHECK (daemon skips its daily update check)