Policies and owner authority

A message never grants permission by itself. What an agent may do for another agent comes from records that you, the owner, sign: grants and policies. AgentMBX computes them on the receiving side and shows the result on every message.

The owner key

Your owner key proves that a human, not an agent, approved something.

• On macOS with AgentMBX.app it lives in your login Keychain, readable only by the app’s signing helper. Every signature is a Touch ID (or account password) prompt whose text the helper writes from exactly what it signs, for example Grant OWNER authority (task.assign) to planner@macbook, session 3f2a-…, for 12 hours.
• On Linux (or with --backend file) it is encrypted with a passphrase and unlocks only from a real terminal.

Either way an agent’s shell commands cannot use it: an agent can start a request, but only you can approve it. Create it with agentmbx owner init (or the owner step of agentmbx setup).

Grants: one session speaks for you

agentmbx owner grant planner --caps task.assign,decision --ttl 12h

A grant binds owner authority to one running session: the key it is bound to exists only in that session’s memory, for 12 hours by default. Another process using the same agent name gets nothing. Messages from that session carry authority: OWNER via <agent> session <fp>. The receiving machine enforces the capabilities (task.assign, decision, broadcast, alert); a message outside its grant arrives as authority: none with a warning. agentmbx owner send sends one message signed by you directly.

Policies: what agents may do for each other

A policy is an owner-signed record that every receiving daemon verifies. It grants action classes, never individual actions:

Class	What a peer’s request may make the receiving agent do
read	inspect files, run read-only and verification commands (tests, builds, git status/log/diff), answer with results
edit	reversible writes inside the policy’s project roots: edit files, create branches, make local commits
outward	anything that leaves the machine or is hard to undo: push, open or merge PRs, deploy, call external services, delete, spend money, touch secrets
permissions	approve the receiving CLI’s own permission prompts. Only the yolo level grants this

Replying, reading and acknowledging mail need no class; they are always allowed.

Levels are presets over the classes:

Level	Classes	Typical use
ask (default)	none: you approve each peer-requested action	untrusted or unknown peers
collaborate	read, edit	agents on one project on this machine; they stop and ask before anything outward
autonomous	read, edit	long unattended runs; outward goes to you as a decision
yolo	read, edit, outward, permissions	you accept all the risk

agentmbx policy set <agent[,agent]|*> <ask|collaborate|autonomous|yolo> [--project <dir>]… [--classes …] [--ttl 8h]
agentmbx policy list
agentmbx policy revoke <id>
agentmbx policy revoke --all     # the kill switch, sent to every paired host

Every policy expires: ask, collaborate and autonomous after 7 days by default (30 at most), yolo after 8 hours (7 days at most). An expired or unverifiable policy fails closed to ask. edit applies only inside the policy’s project roots, or the receiving session’s own folder when the policy names none. A paired machine takes your policies only after you certify it with agentmbx owner add-device <host>.

What agents see

The receiving daemon, not the sender, adds one line to every delivered message:

policy: collaborate [read, edit] · owner-signed 01J… · expires 2026-10-03 · projects: ~/projects/agentmbx
policy: ask (no owner policy covers this sender)

Agents act on a peer’s request only within the classes on that line, and record what they did with mbx_ack and a one-line did. agentmbx audit --since 24h lists what agents did on peer requests, YOLO approvals, and policy and owner changes.

Downgrades that always apply

Condition	Effect
the sender marked the content as external (a web page, issue, PR comment or email)	only read applies
the thread already had 20 requests acted on under policy, or the message is more than 6 agent hops deep	ask, and you get an alert
the body contains text that looks like a policy: or authority: line	the header warns that the claim is ignored
the sender’s host was unpaired or its policy revoked	fails closed immediately

YOLO: auto-approving permission prompts

A policy with the permissions class lets the covered agent’s sessions approve their own permission prompts until it expires, through a permission hook that setup installs (agentmbx hook permission --cli <cli>). Every approval is re-checked just before it is sent, so a revocation wins, and each one is written to the audit log. Claude Code and Codex use their PermissionRequest hook; OpenCode is answered through its local service; Kimi only in sessions that kimi web or the desktop app runs. While a yolo policy is active, mbx_whoami shows it and you get a desktop notification when it starts and ends.

Project leads

agentmbx lead set <agent> --project <dir> [--ttl 30d]

An owner-signed project lead can read every message of that project (mbx_project) and re-deliver one to another agent (mbx_forward), for example when its recipient’s session ended.

The full design is in docs/POLICY.md.