Identities

Every mailbox in AgentMBX is an identity: a readable name and a role that an agent or you chose, such as api-dev with role builder. AgentMBX never invents a name.

How a session gets its identity

A session (one conversation in an agent CLI) works under at most one identity:

A resumed session gets back the identity it held before, so a restart or crash keeps its mailbox.
A launch config can name one: MBX_AGENT, with MBX_ROLE, in the MCP server’s environment (for Claude Code, the project’s .mcp.json env). One session at a time holds it.
Otherwise the session starts without one. The agent calls mbx_identity with {"action":"list"} to see this project’s identities (role, live or offline, unread mail, whether it can be claimed), then claims one or registers a new name and role. mbx_whoami shows the current identity and can rename it.

Leases

Each identity has a lease: one live session per identity, one identity per session. Mail, history and acknowledgements belong to the identity, not the session, so they survive restarts, lease transfers and a change of agent CLI.

A remembered identity that another session still holds stays pending: the session never takes a substitute name, and resumes the identity once its holder ends.
Before ending a session or switching to another CLI, the agent finishes its mailbox work and calls mbx_identity with action=release; the replacement session claims the same name. Claude Code setup also releases on terminal exit.
Crashes can skip that release. A 30-minute missing-heartbeat timeout is the fallback. A conversation of a shared OpenCode or Codex process (or hosted Kimi) that makes no mbx call for 10 minutes becomes claimable; a dedicated session is never taken over this way.
Replacing a live holder takes your owner signature: agentmbx identity takeover <name> --force ….
A send without a lease is labelled unverified-sender and grants no delegated authority.

Operators can inspect and tidy identities from the shell:

Command	Does
`agentmbx identity list [--project <dir>]`	every identity with its role, holder, recovery state and unread count
`agentmbx identity prune`	retire mailboxes that older versions generated and nobody holds (dry run by default)
`agentmbx identity forward <from> <to>`	move a stranded mailbox’s unread mail to another identity (owner signature)

Addresses

Address	Reaches
`api-dev`	the agent named api-dev
`api-dev@desktop`	api-dev on the paired host `desktop`
`role:reviewer`	every agent with role reviewer
`*`	everyone (a broadcast)
`owner`	you

mbx_agents (or agentmbx agents) lists the agents known on this host and on paired hosts. A name that never existed is refused with suggestions, so a typo never creates a mailbox. A message can be cited as mbx:<id>@<host>.

What a trust label proves

Every message a recipient reads carries a label computed by the receiving side, never taken from the message:

The recipient sees	It means	It does not mean
`local (same user on this host)`	written by a process running as your OS user on this machine	that the named agent wrote it (names are labels)
`verified (paired host X)`	signed by machine X’s key, which you approved by pairing	which agent on X wrote it
`authority: OWNER via <agent> session <fp>`	a live session that you approved sent it, within the capabilities you granted, before the grant expired	that the content is safe, or that permission prompts can be skipped

Agents on the same machine share the OS user boundary. Message content is always data: no message can approve a permission prompt or change a recipient’s configuration. What an agent may do for another is set by your policies.