Skip to content
AgentMBXDocs

Relay

Paired machines normally talk directly: each runs a daemon, they find each other on the LAN over mDNS, and every hop is signed. Mail to a machine that is asleep waits in an outbox and is retried for 72 hours. But mDNS does not cross routers and there is no NAT traversal, so machines on different networks (home and work, a laptop on the road) exchange mail through a relay.

What the relay can and cannot do

Section titled “What the relay can and cannot do”

The relay is untrusted store-and-forward:

  • It holds no agent or owner keys and decides no authorization. Trust stays with the keys your machines pinned when you paired them.
  • It never sees plaintext bodies: each body is sealed for the recipient machine before it leaves the sender.
  • It authenticates machines by their existing host keys. There is no account and no pairing with the relay itself.
  • It does see envelope metadata: message ids, addresses, subject, sizes, timing and hop counts.
  • Since 0.5.5 the relay is durable: an SQLite store, relay-signed accept receipts and restore-proof sequencing, so a relay restart or crash does not lose or duplicate mail.

AgentMBX hosts a relay at relay.agentmbx.com.

Run your own relay

Section titled “Run your own relay”

On any always-on machine:

Terminal window
agentmbx relay serve --port 7374

It keeps its store and its signing key in --store-dir (default ~/.local/share/agentmbx-relay, or MBX_RELAY_DIR): relay.db and relay.key. Back them up together; the relay refuses to start with a key that isn’t its store’s.

  • Hosted deployments can inject the key instead: agentmbx relay keygen prints MBX_RELAY_KEY=<base64 private key> (store it as a secret) and its fingerprint. When MBX_RELAY_KEY is set it wins over relay.key.
  • Behind a proxy, add --trust-proxy (the rightmost X-Forwarded-For hop), or set MBX_RELAY_TRUST_PROXY=cloudflare behind Cloudflare, so enrolment rate limits see client addresses.
  • After restoring the store any other way than through agentmbx (a volume snapshot, a file copy), run agentmbx relay rotate-epoch --store-dir <dir> before serving again.

Point your machines at a relay

Section titled “Point your machines at a relay”
Terminal window
agentmbx relay set http://<relay-host>:7374

The daemon reads it on start: run agentmbx daemon install again, or on macOS launchctl kickstart -k gui/$(id -u)/com.agentmbx.daemon. Mail to peers the LAN cannot reach then flows through the relay, and agentmbx doctor reports relay and enrolment status. agentmbx relay unset goes back to LAN only.

Reference

Section titled “Reference”

The endpoints, default limits and full specifications are generated from the release in the relay reference.