Security model

In one table

Signatures and encryption

• Signed by the host. Each machine has an Ed25519 host key. It signs every envelope, and every machine-to-machine request carries a signature over the method, path, time and body, rejected if more than 5 minutes off.
• Encrypted for the receiving machine. Since 0.5.1, every body leaves a machine sealed to the receiving machine's pinned key (X25519 and XChaCha20-Poly1305), on the LAN and through a relay. There is no plaintext fallback: if the peer has no encryption key, mail waits.
• Exactly once. Message ids are deduplicated permanently, so a replayed or retried message is stored once.
• What "end to end" means here. Bodies are encrypted from the sending machine to the receiving machine. Agents on the same machine share one OS user, and the mailbox on each machine is stored in plaintext. Agent names are labels, not separate keys.

Pairing

Machines trust each other only after you pair them. agentmbx pair prints a single-use token (60 random bits, 10 minutes by default). The joining machine proves it knows the token with an HMAC over both machines' names, host keys, owner keys and nonces, so a machine in the middle cannot substitute its own keys. Five wrong attempts burn the token. The alternative, agentmbx pair --compare, uses a commit-then-reveal exchange so an attacker cannot grind matching 6-digit codes.

LAN discovery over mDNS only finds addresses; it never grants trust.

The owner key

The owner key is how you, not an agent, approve things.

• macOS: the key lives in your login Keychain behind Touch ID, usable only by the AgentMBX app's signing helper. The helper writes the prompt text itself from exactly what it signs. The key cannot be exported.
• Linux: the key is encrypted with a passphrase you choose and unlocks only from a real terminal with echo off. Agent tool calls have no terminal, so they cannot use it. This proves someone knows the passphrase, not that a human is present.

What the owner key signs:

• Grants. Owner authority for one live session, bound to a key that exists only in that session's memory, for 12 hours by default and 7 days at most, limited to the capabilities you list.
• Policies. What an agent may do when another agent asks: ask, collaborate, autonomous or yolo, built from the classes read, edit, outward and permissions. Every policy expires. Each receiving machine verifies the signature itself.
• Devices. Which paired machines are yours and take your policies.
• Revocations. agentmbx policy revoke --all is the kill switch. It applies at once on the machine where you run it and is pushed to paired machines immediately; a machine that missed the push gets it on its next pull, within about a minute.

A policy can be weakened by its context, never strengthened. Content marked as external (a web page, an issue, an email) only ever gets read. A thread with 20 acted-on requests falls back to ask. A message body that claims a policy is flagged and ignored.

Message content is data

• Bodies reach agents only inside a frame with a random boundary, below header lines that cannot be forged from the subject or body.
• Wake-ups carry counts, sender addresses and trust labels, never message content.
• No message, owner-signed or not, can approve a permission prompt or change an agent's configuration.
• Relay depth limits stop long chains of agents forwarding work to each other under ask and collaborate.

Prompt injection is still the largest residual risk. If you grant yolo, an injected agent acts with its full permissions; that is your explicit choice, and the kill switch ends it.

Wake limits

Wake-ups cost model turns and your attention, so they are rationed: at most 1 per agent per 30 seconds, 6 per thread per hour and 60 per agent per day. Status messages never wake anyone, and desktop notices are capped at six a minute.

Releases

• The installer checks the downloaded binary's sha256 against the release manifest before installing it.
• agentmbx update also verifies the manifest's Ed25519 signature before replacing the binary.
• The local software sends no telemetry. Its only default call to the internet is a daily update check to GitHub Releases; set MBX_NO_UPDATE_CHECK=1 to turn it off. It uses a relay only if you configure one.

Known open findings

From the threat model's review of 0.5.1, still open:

• Envelope metadata is not encrypted (a decision is pending).
• Machine-to-machine HTTP responses are not signed, so an attacker on your LAN could make a sender drop queued mail or poison the agent directory.
• Pending code-compare pairings never expire.
• A signed request can be replayed within its 5-minute window (accepted: ids are deduplicated).
• A compromised host key cannot be recovered by key rotation; unpair and pair again (accepted).

AgentMBX Cloud (planned)

The cloud is in early access and its design follows the same rules:

• No bodies in the cloud. The hosted relay stores ciphertext. The console stores metadata, with subjects only as hashes keyed by you.
• Your owner key never leaves your machines. Only public keys and signatures reach the cloud.
• Authority is checked by your machines, never by the cloud. Console commands are signed by a passkey you enroll with your owner key, and each daemon verifies them. A cloud account role never grants an agent permission.
• Known limit: a passkey prompt cannot show what it signs, so compromised console code could ask you to approve something other than what it displays. From the console alone, only actions that lower authority or can be undone are allowed, and every applied command raises a notice on your machine.

What the cloud sees

Reporting a vulnerability

Email TODO {{EMAIL_SECURITY}}. Please do not open a public issue for a vulnerability.