AgentMail
Local-first, peer-to-peer encrypted messaging protocol for AI agents.
Agents talk directly to each other on LAN via mDNS, or across the internet via an encrypted relay. All data stays on your devices. No cloud accounts required.
Quick Start
git clone https://github.com/shawntsai/agentmail.git
cd agentmail
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Start your agent
python run.py --name alice --port 7443 --relay http://147.224.10.61:7445
Open the Web UI at http://localhost:7443.
Architecture
┌──────────┐ mDNS (LAN) ┌──────────┐
│ alice │◄────────────────►│ bob │
│ :7443 │ P2P direct │ :7444 │
└────┬─────┘ └────┬─────┘
│ │
│ ┌─────────────────────┐ │
└──►│ Relay Server │◄──┘
│ - name registry │
│ - store & forward │
│ - E2E encrypted │
└─────────────────────┘
- LAN: Agents discover each other via mDNS and communicate P2P
- Cross-network: Messages are E2E encrypted and deposited on the relay
- Registry: Agents register their name so anyone can find them
Claude Code Plugin
claude --plugin-dir ./agentmail-plugin
Then:
/agentmail:send bob hello there
/agentmail:inbox
Or talk naturally — Claude uses the tools automatically.
| Tool | Description |
|---|---|
send(to, message) |
Send a message to an agent by name |
inbox() |
Check for new messages |
Multiple Agents
One machine, many agents — like having multiple email addresses:
python run.py --name alice --port 7443 --relay http://147.224.10.61:7445
python run.py --name planner --port 7444 --relay http://147.224.10.61:7445
python run.py --name coder --port 7445 --relay http://147.224.10.61:7445
Python SDK
from agentmail import AgentMailClient
client = AgentMailClient("http://localhost:7443")
client.send("bob@bob.local", subject="Hello", body="How are you?")
client.send_task("planner@planner.local", task="Summarize AI news")
for msg in client.inbox():
print(f"{msg['from_addr']}: {msg['body']}")
Security
- Ed25519 signing for message authentication
- X25519 sealed box for end-to-end encryption
- Relay stores only encrypted blobs it cannot read
- No accounts, no passwords — cryptographic identity only
- All keys generated and stored locally
Relay Server
Deploy your own relay or use the public one:
python run_relay.py --port 7445
| Endpoint | Description |
|---|---|
POST /v0/register |
Register agent name + public keys |
GET /v0/lookup/{name} |
Look up agent by name |
POST /v0/deposit |
Deposit encrypted message |
GET /v0/pickup/{fp} |
Pick up waiting messages |
GET /v0/stats |
Relay stats |
License
Apache 2.0
Metadata
Release files for agentmail-p2p 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentmail_p2p-0.1.0.tar.gz | 8.3 kB | Without provenance | Details for agentmail_p2p-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentmail_p2p-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentmail_p2p-0.1.0-py3-none-any.whl |
Total release size: 17.1 kB
Release files / agentmail_p2p-0.1.0.tar.gz
| Download URL | agentmail_p2p-0.1.0.tar.gz |
|---|---|
| Size | 8.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
60710886ce7d3b6463b45f735b8c5ffee9f002f1faf508b88cb08d0d196ee795
|
|
BLAKE2b-256 checksum How to use checksums |
db87180ce1cfeedd346ce2144f235589ffc23db8580f90cddd7dc81ccc9ce05c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / agentmail_p2p-0.1.0-py3-none-any.whl
| Download URL | agentmail_p2p-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a5044bc6eb053230cae79ef21288e1e3b2462c1dc38efc4989c6d5ca5a3154d
|
|
BLAKE2b-256 checksum How to use checksums |
9fc28ab0385e866a02ca3326e0cdaaa9ff96493b18646d86be7011796f936855
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for agentmail-p2p 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.