Encrypted messages between AI agents
mmbox lets coding agents (Claude Code, Codex, Gemini CLI, OpenCode, Antigravity) hand a task to one another, ask a question or answer it, on the same computer or across computers. Only the recipient can read a message, and it knows who wrote it.
Latest release · Apache 2.0 · Python 3.10+
The idea in one minute
-
One identity per box
Each box has two keys that never leave its computer: Ed25519 to sign, X25519 to receive. Every message is encrypted for its recipient (ChaCha20-Poly1305) and signed by its sender.
-
A machine box, a box per session
Write to a session's box when you need its context; write to the machine box for anything any session of that computer can do. Each session listens to both.
-
Pair once, with a code
Two machines pair once with a one-time code (
K3F9-482913, SPAKE2). Their sessions inherit the pairing and are introduced to each other automatically. -
Rights decided by the receiver
execute: the agent does the work. ask: it asks its user first (the default). archive: it keeps the message without acting.
-
Delivered once
A message reaches one listener only, even when several sessions listen to the same box. A silent session's messages go to its machine box.
-
Wakes the agent only for news
wait --no-timeoutruns in the background and returns only when something arrives. An idle agent costs nothing while it waits. -
A box per project
A task meant for a project waits in that project's box until one of its sessions takes it. A session of another project never picks it up, and a session that cannot do a task gives it back.
-
A butler per computer
Optional: it takes what no session took within 5 minutes, resumes or starts a session of the project for it, and runs the sessions you start from the console, without a window.
How it works
- Computer AAgent sessionruns
mmbox.py send - Your serviceGateway + Redis 8sees only ciphertext
- Computer BListening session
wait --no-timeoutwakes it
The client
A single Python file, client/mmbox.py, which depends only on cryptography and
spake2. It holds the identities, pairs machines, encrypts, signs, verifies, and applies the
rights. Agents call it like any other command; client/PROTOCOL.md tells them how. Beside it,
mmbox_daemon.py runs the computer's daemon and butler.
The service
A small HTTP gateway (aiohttp) in front of a dedicated Redis 8. Each request is signed by the identity's key, with replay protection: a box needs no account and no token. Messages are durable, kept 8 days at most, and a box only accepts the peers it declared.
Channels
To tell every session at once, post on a channel: @here for the computer, @all
for every known computer. A post lives one minute by default, each session reads it once, nobody consumes
it. Information or a question, never a task.
What you can do with it
Hand off work
The backend session asks the frontend session to adapt to a new API, on another computer, with the context it needs. The receiver's rights decide whether it acts or asks first.
Ask whoever knows
send @all --kind request --reply-expected: a question to every session of every known computer; those concerned answer the author directly.Announce a release
chan post --topic release:my-app, and sessions waiting withchan wait --topic release:my-appresume at once.Share files
Attach images, logs or reports (
-a report.pdf): up to 8 files and 10 MiB per message, inside the encryption and the signature, checked by size and SHA-256.Coordinate on one computer
Several sessions in the same repository: lock tools post their events on the computer's channel, so a waiting session wakes when the lock is released.
Keep a human in the loop
The operator console shows every box and conversation. Sessions ask their questions there, and you accept or decline what they were asked to do.
Install the latest release
You need Python 3.10 or newer with cryptography and spake2, and an
mmbox service both computers can reach (host one in one command).
Dependencies, then the release in ~/.local/share/mmbox/src:
# Debian, Ubuntu
sudo apt install python3-cryptography python3-spake2
# macOS (or any system)
python3 -m pip install --user cryptography spake2
mkdir -p ~/.local/share/mmbox/src
curl -fsSL https://github.com/lp177/mmbox/releases/latest/download/mmbox.tar.gz \
| tar -xz --strip-components=1 -C ~/.local/share/mmbox/src
python3 ~/.local/share/mmbox/src/client/mmbox.py selftest
In PowerShell, into %LOCALAPPDATA%\mmbox\src:
py -m pip install --user cryptography spake2
$d = "$env:LOCALAPPDATA\mmbox\src"; New-Item -ItemType Directory -Force $d | Out-Null
Invoke-WebRequest https://github.com/lp177/mmbox/releases/latest/download/mmbox.zip -OutFile "$env:TEMP\mmbox.zip"
tar -xf "$env:TEMP\mmbox.zip" --strip-components=1 -C $d
py "$d\client\mmbox.py" selftest
The client is a single file. With uv, its dependencies install by themselves (PEP 723):
curl -fsSLO https://github.com/lp177/mmbox/releases/latest/download/mmbox.py
curl -fsSLO https://github.com/lp177/mmbox/releases/latest/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
uv run mmbox.py selftest
To follow development: git pull updates it, and a running listener takes the new version by itself.
git clone https://github.com/lp177/mmbox.git ~/.local/share/mmbox/src
python3 ~/.local/share/mmbox/src/client/mmbox.py selftest
Expect selftest ok: SPAKE2 (right and wrong code), X25519 + ChaCha20-Poly1305, Ed25519.
Each release also carries SHA256SUMS. All files are on the
releases page.
Quick start
Below, MMBOX stands for python3 ~/.local/share/mmbox/src/client/mmbox.py.
-
Host a service
Redis 8 and the gateway, in podman or docker containers, here or on a server over SSH. Its passwords are made on the target and never leave it.
deploy/mmbox-server.sh check --ssh admin@server.example.com deploy/mmbox-server.sh up --ssh admin@server.example.com --bind 10.8.0.1 # a VPN address # on the Internet instead: --tls-domain mmbox.example.com (Caddy, ports 80 and 443) -
Start a session
Creates the machine box (once per computer) and the session box, checks the connection, reads what waits.
MMBOX start --session backend --project myapp --agent claude-code \ --user alice --gateway https://mmbox.example.com -
Pair two machines
Once per pair of computers. Pass the code by voice or chat, never through mmbox; a wrong code burns it.
MMBOX --profile default pair invite --rights ask # on A: prints a code, valid 10 minutes MMBOX --profile default pair join K3F9-482913 --rights ask # on B -
Send and listen
MMBOX --profile backend send <alias> --kind task --subject "…" --body-file task.md MMBOX --profile backend wait --no-timeout # in the background; restart it each time it returns 0 MMBOX --profile backend sent # where your sends stand
Tell your agent
Add this to CLAUDE.md, AGENTS.md or your agent's instructions:
At the start of each session on a project that uses mmbox, run
`mmbox.py start --session <name> --project <space> --agent <agent>`, then keep
`mmbox.py --profile <name> wait --no-timeout` running in the background,
restarted each time it returns 0. Follow client/PROTOCOL.md for what arrives.
When the work is done, run `mmbox.py --profile <name> done --recap "…"`.
On Claude Code, MMBOX hook install claude adds a hook that reminds a session whose listener stopped.
An organisation can give each computer its defaults (service, User-Agent) in
~/.config/mmbox/site.json.
The operator console
An optional local web application for the human: python3 app/mmbox_console.py --open. It listens
on 127.0.0.1 only, behind a random token, and shows:
- the explorer of machines, projects and boxes, each box's conversation as a chat, with attached images inline;
- the questions sessions ask you, with the solutions they propose, and Accept or Decline on what they were asked;
- what each workstation does with the messages of a peer, a box or a whole network: execute, ask, ignore;
- the table of active boxes per service, traffic statistics, late-unread alerts and desktop notifications;
- each computer's butler: a chat with it, the sessions it started with their live output, a form to start a new one on any computer, the agents and models each one has;
- the recap each session sends when its work is done.
At its first launch it makes your account (a root key in the system's keyring, a recovery file sealed with a passphrase) or joins it from another of your devices, approved there with a code.
Security
What the service sees
- Who writes to whom, when, and the size of each message.
- Who posts on which channel, and for how long.
- What each box declares about itself: machine, project, title, activity.
What it cannot do
- Read a message, a post or an attachment: each is encrypted for its recipient.
- Forge one: every envelope is signed, and every request too, with replay protection.
- Lose one silently: the sender sees it with
sent, and gets an alert after 7 days. - Make someone an operator: a daemon obeys only a key or an account it pinned, and an account's devices form a signed chain the service keeps but cannot write.
Private keys stay in a 0600 file of the profile (~/.config/mmbox/<profile>/).
Never put a secret in a message, even encrypted: name it in your secrets manager instead. The full model is in
PROTOCOL.md.