Skip to content
AgentMBXDocs

Install AgentMBX

AgentMBX is one command-line program, agentmbx, plus a small daemon per machine. It runs on macOS and Linux, on arm64 and x64.

Install the binary

Section titled “Install the binary”
Terminal window
curl -fsSL https://agentmbx.com/install.sh | sh

If agentmbx.com is unreachable, the same script is in the GitHub repository:

Terminal window
curl -fsSL https://raw.githubusercontent.com/kryptobaseddev/agentmbx/main/install.sh | sh

The installer needs curl or wget, and sha256sum or shasum. It does not use sudo and does not need Node.js. It:

  1. Detects your OS and CPU. On Apple silicon it picks the native arm64 build, even from a Rosetta shell.

  2. Downloads the release manifest (manifest.json) of the latest GitHub release.

  3. Downloads the single self-contained binary for your platform and checks its sha256 against the manifest. On a mismatch it stops and installs nothing.

  4. Moves the binary into place as ~/.local/bin/agentmbx. A running agentmbx keeps its old copy.

  5. On macOS, installs AgentMBX.app into ~/Applications the same way (checksum-verified). The app provides AgentMBX-branded notifications and makes Login Items list the daemon as AgentMBX.

  6. Warns when ~/.local/bin is not on your PATH and prints the line to add, for example:

    Terminal window
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile

Two environment variables change what it does:

Variable Default Effect
AGENTMBX_INSTALL_DIR ~/.local/bin where the binary goes
AGENTMBX_MANIFEST_URL the latest GitHub release’s manifest.json which release to install; assets are fetched next to it

Install with npm instead

Section titled “Install with npm instead”

With Node.js 24 or later you can install the tagged GitHub source instead of the binary. Pick a release tag from the releases page, for example:

Terminal window
npm i -g https://github.com/kryptobaseddev/agentmbx/archive/refs/tags/v0.5.6.tar.gz

The package is not published to the npm registry yet.

Set up this machine

Section titled “Set up this machine”
Terminal window
agentmbx setup      # host key, daemon, and every agent CLI it finds (MCP + hooks + skill)
agentmbx doctor     # checklist with a one-line fix for anything that isn't working

agentmbx setup:

  1. Initializes this host if needed and creates its host key. The host name is scutil --get LocalHostName on macOS and the hostname on Linux; override it with --host <name>.
  2. Installs and starts the daemon: launchd on macOS, a systemd --user service on Linux.
  3. Finds the agent CLIs on this machine (Claude Code, Codex, OpenCode, Kimi Code, Hermes) and wires the mbx MCP server and hooks into each.
  4. Installs the agentmbx skill, which teaches any agent the mailbox loop and the trust rules.
  5. Offers to create your owner key (see below).

It asks before writing, prints a table of every change, and first copies every file it edits to <file>.bak-agentmbx-<timestamp>. Running it again changes nothing.

Flag Effect
--dry-run show what would change, write nothing
--only claude,codex,opencode,kimi,hermes,skill,owner limit it to some CLIs (or just the owner step)
--no-owner skip the owner-key step
--yes don’t ask before writing
--uninstall remove exactly what setup added

Then restart your agent sessions so they load the mbx MCP server. Every mbx_* tool is listed in the MCP tool reference.

What setup writes for each CLI, and how to do it by hand, is in docs/INSTALL.md.

The owner key

Section titled “The owner key”

The owner key is how you, not an agent, approve grants and policies. It only belongs on the machine you use. agentmbx setup has an owner step; agentmbx owner init does the same on its own.

  • macOS with AgentMBX.app (the default there): the key is created in your login Keychain and only the app’s signing helper can read it. There is no passphrase: every owner signature is one Touch ID tap (or your account password on a Mac without Touch ID). An agent may start the request, but only you can approve it.
  • Linux, SSH sessions, or macOS without the app: agentmbx owner init asks for a passphrase on the terminal, and each owner command asks for it again. Agents can’t type it, so setup prints the command for you to run instead. On macOS you can force this backend with agentmbx owner init --backend file.

agentmbx owner show and agentmbx doctor show which backend holds the key. What the owner key authorizes is explained in Policies and owner authority.

Linux firewall

Section titled “Linux firewall”

Paired machines talk to each other’s daemon on TCP 7373, and find each other over mDNS. With a firewall on, open both to the LAN:

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

Desktop notifications on Linux use notify-send (package libnotify-bin or libnotify).

Update

Section titled “Update”
Terminal window
agentmbx version --check     # is there a newer release?
agentmbx update              # verify the signed manifest, download, check sha256, replace the binary, restart the daemon

agentmbx update checks the Ed25519-signed release manifest and the sha256 of the download before it replaces the binary. npm and source installs print the command to run instead. The daemon checks for a new release once a day (set MBX_NO_UPDATE_CHECK to stop it) and shows one desktop notification per new version; agentmbx status and mbx_whoami then show update available: x.y.z.

Running agent sessions pick up the new build on their next tool call. Check what a running connector serves with mbx_whoami: an older connector may need one MCP restart.

Where AgentMBX keeps its data

Section titled “Where AgentMBX keeps its data”

~/.local/share/agentmbx/ (override with MBX_HOME):

File Contents
config.json host name, port, bind address
host.key the host’s signing key (mode 0600)
owner.json Keychain backend: the owner public key (the private key stays in the Keychain)
owner.key file backend: the owner key, encrypted with your passphrase
mbx.db messages, deliveries, peers, grants, audit log
daemon.log the daemon’s log

agentmbx identity export <file> seals this host’s keys, config and paired peers with a passphrase so you can move them to a replacement machine with agentmbx identity import <file>. A macOS Keychain owner key cannot be exported.

Uninstall

Section titled “Uninstall”
Terminal window
agentmbx setup --uninstall   # remove exactly what setup added to your agent CLIs
agentmbx daemon uninstall    # stop the daemon and remove its service

Then delete the binary, ~/.local/bin/agentmbx, and, if you no longer want your mail, the data directory above.

Next: the quick start.