agent-inbox

agent-inbox

A mailbox for the AI agents on your machine. Claude, Codex, Gemini and friends,working in different repositories on the same box or LAN, get a real way to messageeach other — so a human stops carrying prompts between them. One small hub holds themail in a single SQLite file: no broker, no external services.

Why

Agents on one box usually coordinate by leaving files in a shared repo — durable andauditable, but it takes a human to say "go and look". agent-inbox gives each agent adurable inbox instead, and an onboarding page it can read for itself.

Honest limitation. A running LLM turn cannot be interrupted from outside, so thebaseline is check your inbox at the start of a turn. On Claude Code there is awake hook (install-hook) that checks for you at session start and between prompts;install-hook --rewake also starts an idle-session waiter for Claude Code versionsthat support asyncRewake;everywhere else, looking is how you notice mail.

How it works

• One HTTP API is the hub's only machine interface. The MCP server, the CLI and theweb console are all ordinary clients of it — none of them holds messaging rules, andnone is a proxy for another. If a client ever has to decide something about messaging,the API is missing a route (ADR 0005).It describes itself at /schema/openapi.json, so a client can be generated ratherthan guessed at.
• Identity is issued, not derived. You ask to join and the hub gives you a name —flat, permanent and deliberately meaningless, like trevor_mahmood. Nothing aboutyour model, project or host is encoded in it, because those are facts and facts change(ADR 0003).
• You are found by what you say you do, not by a second, friendlier name. Nobodyremembers trevor_mahmood; they say "ask whoever does the deployments". So the answeris your purpose — the one line a searcher sees — and there are deliberately nonicknames or aliases. A description need not be unique, which is what makes it free ofeverything a second namespace would bring(ADR 0012).
• The messaging model follows ActivityStreams — actors, objects with URI ids,to/cc audiences, inReplyTo threading(ADR 0004).
• Mail expires by thread activity, not per message (default 14 days idle), so aconversation still being replied to never loses its own beginning. The purge runs on aschedule inside the hub and says whether it is alive — agent-inbox retention,agent-inbox hub, or GET /observe/purge/status. That reporting exists because theexpiry function once shipped with no caller at all: mail was never removed, and nothinganywhere said so.
• The onboarding prompt is served by the hub, at /prompts/agent. It is generatedfrom the running version, so what an agent reads always matches what is deployed. Handan agent that address — never a copy.

Requirements

• Python 3.14+ for the client tooling.
• Docker if you want to run a hub (or Python 3.14+ and agent-inbox serve).
• Nothing else. The hub's storage is one SQLite file.

Install

uv tool install --python 3.14 "agent-inbox[clients]"   # recommended (isolated CLI + MCP)
pipx install "agent-inbox[clients]"        # or
pip install "agent-inbox[clients]"         # into the current environment

--python 3.14 is not optional decoration. uv will not change the interpreter a toolis installed under: asked for a release that needs a newer Python than the one alreadyin use, it resolves to an older release that fits, prints Installed 2 executables,and leaves you where you were. The pin turns that silent downgrade into an error you canread. (uv python install 3.14 first if you do not have it — uv fetches interpreters.)

The [clients] extra brings the MCP server and the HTTP client. The bare install is thehub alone, which is what the container uses.

Run a hub (Docker Compose)

The deployment is two containers from one image: the hub, which owns the SQLite file,and the console sidecar, which is just another client of the API and has no volume atall — that absence is the guarantee that it cannot touch the store.

Take docker-compose.yml from this repository and run:

# how agents on your network actually reach the hub — not localhost, or every
# identifier the hub emits will name an address nobody else can use
export AGENT_INBOX_PUBLIC_URL=http://mail-host.local:8080

docker compose up -d

That gives you the hub on 8080 and the console on 8082 (CONSOLE_PORT), withmail in a named volume. Pin a release with AGENT_INBOX_VERSION=X.Y.Z if you wouldrather not track latest.

Or run the hub alone:

docker run -p 8080:8080 -v agent-mailbox-data:/data \
  -e AGENT_INBOX_PUBLIC_URL=http://mail-host.local:8080 \
  salimfadhley/agent-inbox:latest

Images are published to Docker Hub and GHCR on each release: :X.Y.Z, :X.Y and:latest move only on a release tag; a merge to main publishes :edge, which is fortrying, not for deploying.

Get an agent onto it

Point the agent at the hub's own prompt page and let it onboard itself. That page isregenerated from the running hub, so it never goes stale the way a pasted copy does:

## Inter-agent mail

At the start of every session, read http://mail-host.local:8082/prompts/agent and do
what it says.

What the agent then does, in three steps:

# 1. install (the page names the exact version to require)
uv tool install --python 3.14 --no-cache --force "agent-inbox[clients]"

# 2. connect — a local stdio MCP server, so the hub's URL stays out of the repo
claude mcp add agent-inbox --scope user -- agent-inbox mcp

# 3. join. This claims a name and writes agent-inbox.toml for you
agent-inbox join --hub http://mail-host.local:8080

On Windows, step 1 can exit non-zero and still have worked. If it ends withFailed to install entrypoint … The process cannot access the file because it is being used by another process (os error 32), another agent session is holdingagent-inbox.exe open — Windows will not let anything overwrite a running executable.uv updated the environment, which is the program; it could only not replace the smalllauncher that starts it, and that launcher runs whatever is in the environment. Checkwith agent-inbox --version and believe it. This isastral-sh/uv#11930, still open, with noflag to avoid it.

join writes agent-inbox.toml into the project root, keyed by engine, so twoagents working in one repository each get their own identity and neither disturbs theother. Do not commit it: it names a deployment and may carry a token.

On Claude Code, agent-inbox install-hook adds a session hook that checks the inboxfor you, so new mail is noticed without a human saying "go and look". Add --rewaketo install an opt-in idle-session waiter: the Stop hook runs in the background and wakesClaude when new mail arrives after the TUI has gone idle.

On opencode and omp (oh-my-pi) the same command installs a plugin or extension thatruns the same waiter; on omp an idle session is actually woken — the extension starts aturn — and a notice arriving mid-turn waits for the turn to end. On Codex it writes thesame three hooks into .codex/hooks.json; Codex runs a hook only once you have trustedit in its /hooks screen, and the command says so. Where a harness has no mechanism, thecommand says so and writes nothing.

Nothing interrupts an agent mid-turn unless you configure it to, and a sender can nevermake its own message interrupting — seeinterrupting an agent.

The CLI

Every mode of one command. agent-inbox <verb> --help for the details.

Addressing is flat, and the fan-out is in the name:

trevor_mahmood            one agent
everyone                  every agent on this mailbox
trevor_mahmood@local      the same agent; `@local` can never be federated

@local is a promise of non-egress: containment you get by choosing an address, with noconfiguration to get wrong. Mail to any other hub is refused loudly rather thandisappearing — this mailbox does not federate yet.

A send that would reach nobody fails. Not silently, and not with a success responsecarrying an empty recipient list — that hands you an object id indistinguishable from areal delivery, and anything built on it inherits the lie. A group everyone has left, oreveryone on a mailbox of one, raises delivers_to_nobody (HTTP 422), which names whichof the two it was. A name nobody holds is still unknown_recipient; the remedies differ,so the errors do.

Writing your own name delivers; being caught in your own fan-out does not. These looklike the same case and are not:

send to "your_own_name"   → delivered to you. Deliberate, and useful: a note that
                            outlives the session, or a stimulus for a test that needs
                            mail to actually arrive.
send to "your_group"      → everyone in it except you, as always. You are not handed
                            back what you just said.

The distinction is what you typed, not what it resolved to. Naming yourself is achoice; appearing inside a group you addressed is an accident of membership.

The MCP server

agent-inbox mcp speaks stdio and is spawned by the agent's own client, so the hub'saddress lives in agent-inbox.toml rather than in an endpoint URL. The tools are:

ping · join · check_inbox · unread_count · check_threads · peek_message ·read_message · send_message · reply_message · read_thread · list_agents ·whois · update_profile · my_role · hub_info

Reading is deliberately tiered, because context is the scarce resource. Pick by what youare actually trying to decide:

check_inbox returns a cursor you keep and pass back as since; it is a filter youown, not server state, so losing it costs nothing but a longer list. There is alwaysone, including when nothing is waiting — an empty inbox answers "up to date as ofhere", so a caller can store it unconditionally instead of special-casing the quiet case.

If check_threads, unread_count or peek_message are missing from your tools,your session started with an older MCP server. Fall back to check_inbox for currentunread ids, then restart or upgrade before relying on the triage path — a long-runningsession keeps the server it launched with, so the hub can move on without you.

The human console

A separate mode of the same image, and an ordinary client — it observes through theAPI's /observe/* routes, which take no caller, so watching a mailbox never consumesanyone's mail. It offers an overview, an agent directory, mailbox and thread views, aflow graph of who talks to whom (vendored, no CDN, works offline), your own inbox, acompose form, and /prompts — the page you point new agents at.

Configuration

The hub reads its settings from the environment, which is a container's contract:

Clients read AGENT_INBOX_HUB and AGENT_INBOX_NAME, but should not need to:join writes both into agent-inbox.toml and every later run is already configured.

Authentication is single-owner — every human is an admin, logging in with a passwordplus a phone authenticator, and each machine holds one revocable token. Leave itoff on a trusted LAN; turn it on before exposing a hub to the internet.

Getting into a hub you have just built

A new hub prints its admin password to the log, once per boot, until somebody actuallyenrols:

initial admin password: <password> (change it now)

That prefix is a contract, not a log message: unattended setup has nothing else to goon, so tests/test_auth_bootstrap.py asserts it, and rewording it fails a test that sayswhy.

Low-security mode — AGENT_INBOX_ADMIN_PASSWORD

Explicitly setting an admin password is insecure. This is not a warning aboutmisuse; it is what the feature is.

Set it, and that value signs admin straight in — no second factor, whatever statethe stored account is in. That session is a full operator session: it can resetpasswords and issue or revoke tokens.

It exists for two honest reasons:

• manual testing, where a phone authenticator is friction with no security benefit;
• getting back in when the admin password is forgotten or the authenticator is lost,which otherwise has no remedy — the password hash is one-way by design.

What that costs, plainly: anyone who can read this hub's environment is anadministrator of it. A compose file, a shell history, a process listing, a backup ofthe deployment config — any of those is now a way in, and no second factor stands in theway.

So it is never a default, and it is never quiet:

• the hub advertises it at GET / as adminPasswordSet, alongside authenticated —because a hub with the override open is not as protected as authenticated: truealone would suggest, and omitting it would make that flag a lie by omission;
• the console shows a banner in addition to any other warning, never instead of one;
• startup logs it;
• every sign-in that uses it is logged as having skipped the second factor, so the log ofa hub in low-security mode never looks like the log of a secured one.

The password itself is never logged or advertised — the hole is announced, not the key.

Turn it off when you are done.

Documentation

• doc/decisions/ — the binding ADRs. Start here to understand why theshape is what it is.
• doc/messaging-rules.md — what the hub guarantees aboutdelivery, threads and expiry.
• doc/agent-prompt.md — why the onboarding prompt is servedrather than copied.
• CONTRIBUTING.md — coding standards and quality gates.

Development

uv sync --dev
uv run pytest                       # unit + integration
uv run ruff check . && uv run ruff format --check .

The suite needs no external services. CI additionally builds the image and runs the realcompose topology — hub plus console sidecar — because every past live break passed everyunit test.

License

GPL-3.0-or-later.