# 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

```bash
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

```bash
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:

```bash
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

```python
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:

```bash
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
