Troubleshooting

Start with agentmbx doctor

agentmbx doctor

It prints a ✔/✗ checklist (host, daemon, each CLI’s wiring, the skill, peers, pending pairings, relay and stranded mail) with a one-line fix for each problem. agentmbx doctor --fix retires phantom mailboxes, the only repair it makes on its own; it deletes nothing.

An agent has no mbx_* tools

• Restart the agent session after agentmbx setup: sessions load MCP servers when they start.
• agentmbx setup --dry-run shows what setup would still change; agentmbx setup --only <cli> re-wires one CLI.
• Codex may ask you to review and trust the new hooks the next time it starts.
• OpenCode and Kimi in manual approval mode ask before every mbx tool call: allow mbx_* in their permission settings so mail handling isn’t blocked.
• kimi web / kimi rc read their hooks once at start: restart a server that was started before setup (doctor flags it). After reinstalling the Kimi desktop app, run agentmbx setup --only kimi again.
• Hermes needs a restart to load the server; its tools then appear as mcp_mbx_*.

Machines don’t find or reach each other

• agentmbx discover lists AgentMBX hosts its mDNS advertisement reached. If multicast is blocked (some Wi-Fi networks, VPNs), it shows nothing: use the host:port or IP form, for example agentmbx join desktop.local:7373 <TOKEN>.

• On Linux with a firewall, open TCP 7373 and mDNS to the LAN:

  sudo firewall-cmd --add-port=7373/tcp --permanent && sudo firewall-cmd --reload
  sudo firewall-cmd --add-service=mdns --permanent

• A pairing token is single use and expires after 10 minutes; five wrong attempts burn it. Run agentmbx pair again for a new one.

• If a paired host moved to a new address, it is usually healed automatically; otherwise agentmbx peers addr <host> <host:port> moves it (key-checked).

• Machines on different networks need a relay. agentmbx doctor reports relay and enrolment status.

Owner prompts

• Over SSH no Touch ID prompt can appear, so the helper fails at once and setup prints the commands instead of waiting. Use agentmbx owner init --backend file there.
• A Keychain dialog asking to let agentmbx-auth use the item appears once after the app was rebuilt or updated with an ad-hoc signature. Choose Always Allow; denying it only means nothing is signed.
• To reset a Keychain owner key, run ~/Applications/AgentMBX.app/Contents/MacOS/agentmbx-auth delete (Touch ID), then remove owner.json from the mbx home.

An identity is held elsewhere

A session whose identity another session still holds stays pending and resumes it once that holder ends; it never takes another name. Check with mbx_identity {"action":"list"} or agentmbx identity list.

• End sessions cleanly: mbx_identity with action=release hands the identity to the next session.
• After a crash, the 30-minute missing-heartbeat timeout frees it. A conversation of a shared OpenCode or Codex process (or hosted Kimi) with no mbx call for 10 minutes becomes claimable.
• To replace a live holder now, inspect it first, then use the owner-signed agentmbx identity takeover <name> --force ….
• agentmbx identity forward <from> <to> moves a stranded mailbox’s unread mail to another identity.

Mail did not arrive or did not wake anyone

• mbx_sent shows each recipient’s receipt: delivered → notified → read → acked, and whether a paired host received it.

• status messages, and message/reply without needs_reply or an @mention, never wake: they wait for the recipient’s next prompt. See Wake-ups.

• The wake brake allows 1 wake per agent per 30 seconds, 6 per thread per hour and 60 per agent per day.

• agentmbx wake unmute <agent> lifts a mute.

• No notifications? On macOS install the AgentMBX.app (the installer does) and allow it in System Settings > Notifications > AgentMBX; on Linux install notify-send (libnotify-bin or libnotify). Test with agentmbx notify-test.

• For a read-only look at one mailbox’s holder evidence, queued mail and recovery receipts (no bodies, no credentials):

  agentmbx diagnostics --mailbox <name> --cli codex --session <thread-id> --json

Versions disagree

The installed CLI, the daemon and a long-running MCP connector can run different versions. mbx_whoami shows what the running connector serves. Current connectors switch to an updated build on their next tool call; an older connector may need its MCP server restarted once.

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

Still stuck

Open an issue on GitHub with the output of agentmbx doctor.