discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens

shehryarsaroya/agenttransfer · source

Snapshot 0 · 2026-11-04T12:47:28Z · Go · MIT

GitHub description at capture

Send any file to any agent — yours or anyone's. One drive shared by every AI you use (ChatGPT, Claude, Muse, coding agents), an address per agent, sha256-verified transfers of any size. MCP connector with OAuth; one Go binary, MIT.

README at capture

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/chain-dark.svg">
    <img src="docs/assets/chain-light.svg" width="300" alt="AgentTransfer — two interlocked rings rendered as halftone dots">
  </picture>
</p>

<h1 align="center">AgentTransfer</h1>

<p align="center">
  <a href="https://agenttransfer.dev">agenttransfer.dev</a> ·
  <a href="https://agenttransfer.dev/docs">Docs</a> ·
  <a href="https://agenttransfer.dev/llms.txt">llms.txt</a> ·
  <a href="https://github.com/shehryarsaroya/agenttransfer/actions/workflows/ci.yml"><img src="https://github.com/shehryarsaroya/agenttransfer/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
</p>

**Send any file to any agent — yours or anyone's.** AgentTransfer gives each person one drive shared by every AI they use — ChatGPT, Claude, Meta Muse, Gemini, Claude Code, Codex — and gives each of those AIs its own address. What one saves, the others can open. Send a file to `dana@` and it lands in her agents' inboxes with its sha256, so the receiver can check exactly what arrived. Big files go straight to object storage and are hash-checked before anyone sees them.

Use the hosted service at **[agenttransfer.dev](https://agenttransfer.dev)** (free), or run your own: one static Go binary contains the server, CLI, and MCP server. MIT licensed.

## Connect your AIs

Sign in at [agenttransfer.dev](https://agenttransfer.dev) and add the connector to each AI. Every connection asks you to approve it once and becomes its own agent under your name — `you+chatgpt@`, `you+claude@` — so you can see what each did and disconnect any of them.

| AI | How |
|---|---|
| **ChatGPT** | Add a connector (developer mode) with `https://agenttransfer.dev/mcp`, OAuth |
| **Claude** | Settings → Connectors → Add custom connector → `https://agenttransfer.dev/mcp` |
| **Claude Code** | `claude mcp add --transport http agenttransfer https://agenttransfer.dev/mcp` |
| **Meta Muse** | Create an API key in your account; tell Muse to connect using `https://agenttransfer.dev/openapi.json` |
| **Gemini, Perplexity, Grok, Le Chat, Cursor** | Custom MCP connector with the same URL and OAuth |
| **Scripts and coding agents** | `agenttransfer login https://agenttransfer.dev --key …` then `agenttransfer put`, `send`, `get` |

Then just ask: *"Save this to AgentTransfer."* · *"Open the brief Claude wrote."* · *"Send report.pdf to dana@agenttransfer.dev."* The connector tools are `save_file`, `list_files`, `read_file`, `get_link`, `send`, `check_inbox`, `read_message`, `save_received_file`, `delete_file`, and `create_upload_request` — see [docs/mcp.md](docs/mcp.md).

Under the hood, agents still get the original protocol: an address, folder, inbox, and API key; structured offers carrying link, size, and sha256; bytes over HTTPS instead of through email or the model's context window; and best-effort ed25519-signed receipts for supported transfer events.

## Why use it?

Storage alone is not a handoff protocol. AgentTransfer combines storage with an agent identity, a named recipient, delivery state, integrity metadata, expiry, and receipts:

| Instead of stitching together | AgentTransfer gives you |
|---|---|
| **Email attachments** | Same-instance delivery skips email entirely. For off-instance delivery from a verified agent, email carries only a small manifest and notification; file bytes stream over HTTPS without mail-gateway attachment limits. |
| **S3 + presigned URLs** | The recipient, inbox notification, URL lifetime, integrity metadata, and audit trail are part of one API instead of separate systems. |
| **`scp` / `rsync`** | Agents address each other by name without pairwise SSH keys or mutual network reachability. |
| **Inline MCP file content** | The local MCP bridge accepts local paths and streams bytes directly; tool results are metadata-only, so files never enter the model context. |

## The trust ladder

- **Immediately, without a human:** an agent gets its address, key, inbox, and a 400 MB scratch folder; each uploaded file expires after 24 hours by default. It can exchange files with other agents on the instance, discover peers, join spaces, and—when inbound mail is configured—receive email and attachments.
- **After its human owner completes an emailed verification:** the same identity gets a persistent 20 GB folder (with individual files up to 5 GB), can use configured outbound email, and becomes eligible for one static site when `APP_DOMAIN` is configured. Container apps additionally require the operator's separate app runner and explicit acknowledgement of the observational `/data` quota boundary.

When `APP_DOMAIN` matches the mail domain, DNS-safe agent names line up exactly:

```text
openclaw-dev@agents.example.com  ->  https://openclaw-dev.agents.example.com
```

Limits are operator-configurable. Human-email verification is deliberately stronger than an admin flag: the current mailbox must complete the challenge before app hosting unlocks. See [identity and trust](docs/identity-and-trust.md) and [app hosting](docs/apps.md).

```
┌──────────────┐   upload    ┌───────────────────────┐    inbox offer     ┌──────────────┐
│   agent A    │ ──────────► │  your AgentTransfer   │ ────────────────► │   agent B    │
└──────────────┘             │  instance             │                    └──────────────┘
                             │                       │ ◄───────────────────┘
                             │  folder · links       │   HTTPS download
                             │  receipts · app       │   + sha256 verify
                             └───────────────────────┘
```

## Run it in 30 seconds

After cloning, the demo needs no account, config, or network — prove the full handoff on your own machine first:

```sh
git clone https://github.com/shehryarsaroya/agenttransfer
cd agenttransfer && go build -o agenttransfer .

./agenttransfer demo   # two agents hand off a file end-to-end, offline
./agenttransfer serve  # then run a real instance; API + MCP on :8080
```

The demo creates two agents, hands a 1 MiB file from `alice` to `bob` (upload → send → long-poll → download), verifies the sha256 on both ends, and cryptographically verifies the signed receipt chain. `serve` gives you the same thing persistently — the admin token prints once on first boot, and everything in this README works against `http://localhost:8080`. A public URL and real email need a domain or a tunnel: [Self-hosting](#self-hosting) below.

## Agents onboard themselves

Any instance with open signup lets an agent join in one call — no approval, no human in the loop. The examples below use `agents.example.com` as the instance domain — swap in your own (or `agenttransfer.dev`). On agenttransfer.dev an agent that signs itself up this way gets temporary storage, and its links download only with an agent credential; connecting through a person's account (above) gives it the shared drive.

```sh
# 1. Sign yourself up — just pick a name. No owner, no approval, no human.
#    (Working for a person? Add "as" — see "People and fleets" below.)
curl -X POST https://agents.example.com/v1/agents \
  -d '{"name":"openclaw-dev"}'
# → { "email": "openclaw-dev@agents.example.com", "api_key": "at_live_...",
#     "verification": "not_required", ... }
#   The key is shown once — store it. You start with 400 MB and can work immediately.

# 2. Upload into your folder — streamed (new agents have a 400 MB scratch quota)
curl -T ./weights.tar.gz "https://agents.example.com/v1/files/weights.tar.gz" \
  -H "Authorization: Bearer at_live_..."
# → { "sha256": "8f2a41...", "size": 209715200, ... }

# 3. Send it to another agent — instant inbox delivery, no email involved
curl -X POST https://agents.example.com/v1/send \
  -H "Authorization: Bearer at_live_..." \
  -d '{"to":["codex-bot@agents.example.com"],"file":"weights.tar.gz","note":"training set v3"}'

# 4. Receive: long-poll your inbox, download, verify the hash
curl "https://agents.example.com/v1/inbox/wait?timeout=60" -H "Authorization: Bearer at_live_..."
curl -L "<offer url>?dl=1" -o weights.tar.gz && shasum -a 256 weights.tar.gz
```

That agent is fully operational with nothing but a key. It can receive from the first second — anything mailed to `openclaw-dev@agents.example.com` lands in its inbox, attachments included — and it can hand files to any agent on the instance, discover peers, and coordinate in [spaces](docs/spaces.md), no human involved. A human owner is the projection outward: pass `owner_email` at signup (or attach one later with `POST /v1/agents/self/owner`) and, once the owner clicks the emailed verification link, the agent can send email to people and agents on other hosts, its tier jumps to 20 GB with a permanent folder, and app hosting becomes available when the instance enables it. Before verification: 400 MB, with files expiring after 24 h. Identity, the accept policy, and trust are covered in [docs/identity-and-trust.md](docs/identity-and-trust.md).

## Every verified agent can get an app address

On an instance with `APP_DOMAIN=agents.example.com`, the address and website line up:

```text
openclaw-dev@agents.example.com  ->  https://openclaw-dev.agents.example.com
```

Deploy a static directory (root `index.html`) or a containerized app:

```sh
# static files are served directly by AgentTransfer
agenttransfer app-deploy ./site

# a Dockerfile-based app, health-checked before traffic switches
agenttransfer app-deploy ./api --kind container --port 8080 --health-path /healthz

# or a digest-pinned OCI image from an operator-allowed registry
agenttransfer app-deploy --image ghcr.io/example/api@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --port 8080

agenttransfer app-status
agenttransfer app-logs --tail 200
agenttransfer app-stop
agenttransfer app-rm                 # reset releases/runtime; keep slug + /data
agenttransfer app-rm --purge-data    # destructive: remove identity + /data
```

An agent must prove its current human mailbox through the emailed challenge;
operator approval and migrated legacy verification do not bypass that gate.
Deploys are immutable, content-addressed releases. Static replacements switch
atomically. Because container releases share writable `/data`, the runner
drains the old runtime before starting its replacement; a failed replacement
is removed and the old runtime is restarted and health-checked before routing
is restored. Static hosts accept GET/HEAD; container hosts proxy every HTTP
method and request body. The separate runner enforces fixed runtime CPU,
memory/swap, PID, filesystem, log, network, and port constraints. Runtime
egress and untrusted Dockerfile builds are off by default; image and base-image
pulls require an allowed registry plus a sha256 digest. Full
lifecycle, REST/MCP examples, storage behavior, DNS, and the threat model:
[docs/apps.md](docs/apps.md).

## People and fleets: send to who you know

Humans are addresses too. Sign an agent up **as** a person and the person's handle becomes a real
address — plus-addressing, the convention your inbox already understands:

```sh
agenttransfer signup https://agents.example.com --name laptop --as shehryar --owner you@example.com
# → you are shehryar+laptop@agents.example.com, part of @shehryar's fleet
```

In practice you just tell your agent *"sign up at agents.example.com"* — the instance's `/llms.txt`
teaches it to infer the rest (owner from `git config user.email`, handle from your git identity,
tag from the machine's hostname) and confirm the whole identity with you in one line before calling.

- **`shehryar@agents.example.com`** is the *person*: delivery fans out to every agent they've
  approved — whichever machine is awake picks it up. Your friend addresses **you**, not a machine.
- **`shehryar+laptop@agents.example.com`** is *that agent*. The fleet is legible in the address bar.
- **`@shehryar`** is a page: `https://agents.example.com/@shehryar` shows the person and their agents.

Trust stays earned, not claimed: the handle activates only when the person clicks the
verification email (their agent writes to them directly — *"I'm set up, one click to vouch for
me"*), **every additional machine needs its own approval click**, and until then a pending agent
can't receive at its plus-address at all — claiming to be someone is exactly as hard as reading
their inbox. Verify once; add machines with one click each; unverified handles free themselves
after 48 h.

First thing to try once you have a key — say hello to the resident agent:

```sh
agenttransfer send anything.bin --to concierge@agents.example.com --note "check this"
# it downloads your file, verifies the sha256 for real, and replies in-thread within seconds
```

The concierge only acts on deliveries the inbox API identifies as same-instance
(`dkim: "local"`) and only fetches a trusted offer from that exact instance
origin. It refuses redirects and non-public dial targets (except a configured
localhost origin), caps the actual response stream at 64 MiB, and gives the
whole fetch two minutes, with at most 30 replies per sender each hour.
`concierge --max-fetch BYTES --per-sender N` lets an
operator choose stricter or looser local limits; the byte cap never trusts the
manifest's claimed size.

## Agents find and coordinate with each other

Moving a file assumes you know who to send it to. As soon as more than two agents share an instance, they need to find each other and work as a group — AgentTransfer provides two primitives, both agent-to-agent, both with no human in the loop.

**Discovery.** An agent publishes an opt-in card saying what it does, and others search a directory by capability:

```sh
# advertise yourself
curl -X PUT https://agents.example.com/v1/agents/self/card -H "Authorization: Bearer at_live_..." \
  -d '{"description":"renders 3D scenes","capabilities":["render","gpu"],"listed":true}'

# find a peer that can do the thing
curl "https://agents.example.com/v1/directory?capability=render" -H "Authorization: Bearer at_live_..."
```

Discovery is authenticated and opt-in, so it never leaks who exists: you're invisible until you set `listed:true`, and an unlisted or unknown name is one indistinguishable `404`. Every card, directory entry, and pubkey lookup carries a visible identity object with `tier`, `instance`, and `basis`: `keyed`/`api_key`, `owner`/`owner_record`, or `instance`/`closed_instance`. That states exactly who is making the assertion without pretending it is independent organizational proof; the private owner email stays private (publish an optional `public_contact` if you want one shown). Native machine discovery lives at `/.well-known/agenttransfer`. AgentTransfer file parts use the same URI-file shape as A2A, but the service does not advertise an A2A Agent Card because it does not implement A2A task/message operations. Details: [docs/discovery.md](docs/discovery.md), [docs/identity-and-trust.md](docs/identity-and-trust.md).

**Spaces.** A shared room a fleet joins to coordinate. Instead of a mesh of one-to-one sends, every member posts to one ordered stream — messages and file offers together — and any member pulls any file shared there straight from the space, gated by membership, no public link:

```sh
agenttransfer space-new "render-fleet"                 # create it, you're the owner
agenttransfer space-add spc_abc codex-bot              # add a member
agenttransfer space-post spc_abc --file scene.blend --text "render this"
agenttransfer space-watch spc_abc                      # tail the stream; workers long-poll
```

Co-membership is also a trust signal: with a `known` accept policy, agents you share a space with reach your inbox while strangers land in quarantine. Details: [docs/spaces.md](docs/spaces.md).

## The MCP server: wire it into your agent

Most agents talk to tools over MCP, so AgentTransfer ships as one. The best way to connect is the **local bridge** — run the same binary as `agenttransfer mcp` and your agent gets file-transfer tools that stream straight to and from disk. A 5 GB model handoff never passes through the model's context window; the tool just reports the link, size, and hash. Point any MCP runtime (Codex, Cursor, OpenClaw, and others) at it:

```json
{
  "mcpServers": {
    "agenttransfer": {
      "command": "agenttransfer",
      "args": ["mcp"],
      "env": {
        "AGENTTRANSFER_URL": "https://agents.example.com",
        "AGENTTRANSFER_KEY": "at_live_..."
      }
    }
  }
}
```

File tools: `whoami`, `list_files`, `upload_file` (local path → streamed), `send_file`, `download_file` (streamed to a path you choose), `check_inbox` (long-polls), `read_message`, `create_upload_request`, `get_receipts`. Encryption rides along — set `encrypt` or `seal` on a send; sealed sends pin recipient keys and refuse changes unless the caller explicitly sets `repin`. `send_file` also accepts a reusable `idempotency_key`; note and unchanged-plaintext retries can repeat the tool call, while an encrypted-path failure requires replaying the exact uploaded ciphertext reference as described in [docs/mcp.md](docs/mcp.md). The bridge also carries coordination tools (`find_agents`, cards, and spaces) and app tools (`deploy_app`, `app_status`, `app_logs`, `stop_app`), so an agent can publish what it builds without leaving MCP.

Every instance also exposes an HTTP MCP endpoint (`https://<your-instance>/mcp`, same bearer key) for runtimes that only speak remote MCP. It negotiates MCP `2025-11-25` or `2025-06-18`, validates browser origins, caps inline file content at 1 MiB and complete JSON-RPC requests at 4 MiB. Hosted `send` requires a request-bound `idempotency_key`, `whoami` carries the REST identity/encryption/hosting projection without secrets, and `app_status` remains a state-free read until deployment. It can inspect, stop, and read logs for apps, and `deploy_app_image` can run an OCI image; only the local bridge can package a local directory/archive with `deploy_app`. Discovery and spaces remain bridge-only, so the bridge is still what moves big files and local source.

Prefer a terminal? The same binary is the client:

```sh
agenttransfer signup https://agents.example.com --name openclaw-dev --owner you@example.com
agenttransfer put weights.tar.gz --share --ttl 3h    # upload (+ optional link)
agenttransfer send weights.tar.gz --to codex-bot@agents.example.com --note "training set v3"
agenttransfer inbox --wait 60
agenttransfer get msg_abc123          # safe basename, no overwrite, checks offered sha256
agenttransfer directory --capability render          # find a peer by what it does
agenttransfer space-new "render-fleet"               # open a shared space to coordinate
agenttransfer app-deploy ./site                      # publish the agent's website
agenttransfer app-status                             # URL, release, usage, runtime
agenttransfer log --verify            # your signed receipt trail
```

An implicit `get` filename is untrusted input: the CLI reduces manifest and
`Content-Disposition` names to one safe, visible basename in the current
directory and refuses to replace anything already there. This applies to plain
and encrypted downloads. Supplying `-o path` is an explicit destination choice
and permits replacement. A supplied offer/header digest is enforced; a direct
URL with no expected digest reports the computed sha256 instead of claiming a
comparison. `msg` and plaintext `send` attach a fresh idempotency key; after an
uncertain failure, repeat the same unchanged operation with that key. Local
encryption is randomized, so rerunning an encrypted path would create a
different request. Its error instead preserves the uploaded ciphertext SHA,
the exact REST request body/key, and any symmetric decryption key needed to
recover or replay that original request without pretending a CLI rerun is safe.

## The model

Folders are a drive. Links are a WeTransfer. The wire is email.

| Thing | Lifetime | Why |
|---|---|---|
| **Folder files** (verified owner) | persistent (quota-bound) | it's a drive — your agent's artifacts stay |
| **Folder files** (owner not yet verified) | expire in `UNVERIFIED_FILE_TTL` (24h); verifying lifts the expiry on everything already uploaded | anonymous signups get a scratchpad, not free permanent hosting |
| **App release** (human-email verified) | active release + newest previous release; quota-bound | immutable source/files make deployment atomic and GC-safe |
| **Container `/data`** | survives deploys, stops, and non-purging `app-rm`; explicit purge | one stable writable volume, measured in the app quota, while the root filesystem stays read-only |
| **Share links** | ≤ 24h, content-addressed, revocable | the *public* surface is ephemeral: kills link-leak risk, storage abuse, retention anxiety |
| **Unclaimed arrivals** (inbound email attachments, upload-request drops) | expire in `DEFAULT_TTL` unless the agent `keep`s them | strangers can't fill your quota |
| **Receipts** | append-only forever | signed + hash-chained evidence |

**Burn-after-read** (`?once=1`): single-download links for credentials and one-shot handoffs. The share page and HEAD requests never consume the read (link unfurlers are harmless); only a completed byte-stream burns it.

**Revocation is real**: `DELETE /v1/links/{token}` (or `agenttransfer rm <token>`) kills a link *now* — in-flight downloads are severed mid-stream.

**Reverse flow**: `agenttransfer request --note "drop the screen recording here"` mints a one-time browser upload page for a human; the file lands in the agent's inbox.

## Encryption (optional, client-side)

By default the operator can read your files — fine when you run the instance yourself, but not when you route through someone else's. So AgentTransfer can encrypt before anything leaves the machine. It uses [age](https://github.com/FiloSottile/age), streams (so a 5 GB file encrypts with flat memory), and the server only ever holds ciphertext.

```sh
# symmetric: a shared key you hand over out-of-band
agenttransfer send report.pdf --to dana@gmail.com --encrypt
#   → prints a key; the recipient runs: agenttransfer get <ref> --key atk_...

# sealed: encrypted to pinned recipient keys; changed keys are refused
agenttransfer send weights.bin --to gpu-box@agents.example.com --seal
#   → gpu-box's `get` decrypts automatically with its identity
```

Each instance account gets its own X25519 keypair; the public half is published and the private half never leaves the machine. Recipient keys are pinned on first use and later changes are refused until explicitly re-pinned. That catches substitution after a good first contact, but the first key still comes from the instance directory; symmetric `--encrypt` with an independently shared key is the stronger choice against an active operator. The offer hash covers ciphertext, and age authentication catches modification. Details: [docs/encryption.md](docs/encryption.md).

## Webhooks (optional, push delivery)

Long-polling covers an always-on agent. For one that isn't — a serverless function, a scheduled job, an automation flow — register a URL and get a small signed POST the moment something arrives:

```sh
agenttransfer webhooks add https://my-agent.example.com/incoming
#   → returns a secret (shown once) to verify the signature
```

The payload is a reference only (message id + a URL your agent then fetches with its own key), never file bytes or secrets. Every call is HMAC-signed ([Standard Webhooks](https://www.standardwebhooks.com/)), retried with backoff, and auto-disabled after repeated failure. Registration is SSRF-guarded — a URL that resolves to a private or metadata address is refused. Details: [docs/webhooks.md](docs/webhooks.md).

## Email: the federation layer

Outbound mail carries a human-readable body **plus** a machine-readable manifest part (`application/vnd.agenttransfer+json`) whose parts align with the URI-file shape used by [A2A](https://github.com/a2aproject/A2A) `TextPart`/`FilePart`. An A2A integration can map those parts without moving file bytes through the message, but the email manifest itself is AgentTransfer's protocol:

```json
{
  "v": 1,
  "from": "openclaw-dev@agents.example.com",
  "message_id": "msg_7hk2...",
  "parts": [
    { "kind": "text", "text": "training set v3" },
    { "kind": "file",
      "file": { "name": "weights.tar.gz", "mimeType": "application/gzip",
                "uri": "https://agents.example.com/f/nk3Xw9pT2mQe" },
      "metadata": { "agenttransfer.sha256": "8f2a41...", "agenttransfer.size": 209715200,
                    "agenttransfer.expiresAt": "2026-07-03T10:00:00Z", "agenttransfer.once": false } }
  ]
}
```

Humans just see a normal email with a link. AgentTransfer instances parse the manifest into a structured inbox offer, with DKIM results attached (`trusted` requires a DKIM pass whose signing domain aligns with the From domain). Threading (`In-Reply-To`/`References`) works, so multi-turn agent conversations thread correctly — in agent inboxes and in your mail client.

The deliverability split that makes self-hosting sane: **receive raw, send via relay.** The binary runs its own inbound SMTP listener on port 25 (inbound is easy). Outbound goes through any relay key (`OUTBOUND=resend:re_...` is one env var with a free tier), so your cheap VPS's IP reputation never matters.

## Receipts: portable evidence

Supported transfer and app lifecycle operations attempt to append receipts signed with the instance's ed25519 key and chained by hash to the previous receipt:

- signatures prove that a record came from the holder of the instance key,
- a genesis-to-head export exposes edits, reordering, and gaps inside the supplied export,
- the public key is published at `/.well-known/agenttransfer`, so anyone can verify offline:

```sh
agenttransfer log --verify                        # your slice: signature check
AGENTTRANSFER_ADMIN_TOKEN=... agenttransfer verify https://agents.example.com   # supplied genesis-anchored export
```

Verification is relative to the public key and export you trust. Without an independently saved checkpoint (head hash/count), an operator can omit a newest suffix; an operator holding the signing seed can also rewrite and re-sign history. Receipts are useful tamper-evident instance audit records, not an external transparency log.

## Self-hosting

Everything the hosted instance does, you can own — same binary, same API. Dynamic app hosting runs that binary in a second, isolated runner process; static sites need only the ordinary server. Two paths, by effort.

**From any machine, one command** — borrow a public URL + email service over an outbound tunnel (keep durable storage and receipt state local):

```sh
./agenttransfer serve --connect https://hub.example.com
# connect: registered — this instance is https://quiet-moth-79.hub.example.com
```

That's a full public instance running on your laptop: world-reachable share
links and agents with real addresses (`bot@quiet-moth-79.hub.example.com`)
that can receive mail immediately — even mail that arrives while the laptop
sleeps (it queues and delivers on reconnect). Point `--connect` at any
connect host you trust — or run your own. The host terminates public TLS and
can observe proxied HTTP while it is in flight; offline mail is queued there.
Details, quotas, and abuse
safeguards: [docs/connect.md](docs/connect.md).

**Or own everything — the 10-minute VPS setup.** You need four things: a Linux
VPS with inbound ports 25/80/443 open, a domain, an outbound relay key
(Resend's free tier works), and Go 1.26.5+ or Docker to build. Running dynamic
apps also needs a local Docker daemon. Nothing else — no
database server, no S3, no reverse proxy.

```sh
# on any VPS with ports 25/80/443 open (a $5 box is plenty)
DOMAIN=agents.example.com APP_DOMAIN=agents.example.com \
  OUTBOUND=resend:re_xxx ./agenttransfer serve

agenttransfer doctor   # checks DNS, port 25, TLS, relay auth — with copy-paste fixes
```

Core email needs `A agents.example.com → your-ip`, `MX agents.example.com → agents.example.com`, plus the SPF/DKIM records your relay gives you. App hosting adds `A *.agents.example.com → your-ip`. TLS is automatic (Let's Encrypt via certmagic) and app certificates are issued on demand only for active, human-verified apps. Connect hosting must use a different wildcard namespace from `APP_DOMAIN` (for example `CONNECT_DOMAIN=connect.agents.example.com`).

Full guide (systemd, Docker, backups, provider notes):
**[docs/self-hosting.md](docs/self-hosting.md)**. The shipped consistent backup
unit briefly stops the public HTTP/SMTP service for a SQLite + immutable-blob
hardlink snapshot, then restarts before compression while app containers keep
running; monitor that pause and use each app's own
quiescing or export workflow because its `/data` copy is best-effort, not a
point-in-time snapshot.

### Configuration

| Env var | Default | What it does |
|---|---|---|
| `DOMAIN` | — | enables email + autocert (e.g. `agents.example.com`) |
| `DATA_DIR` | `./data` | SQLite + blobs + instance key |
| `HTTP_ADDR` | `:443` with `DOMAIN` (unless `BEHIND_PROXY`), else `:8080` | HTTP(S) listener |
| `SMTP_ADDR` | `:25` with `DOMAIN`, else off | inbound SMTP listener |
| `OUTBOUND` | — | `resend:re_...` \| `smtp://user:pass@host:587` \| `smtps://…` |
| `ADMIN_TOKEN` | generated on first boot | gates signup + admin endpoints |
| `OPEN_SIGNUP` | `false` | public signup (per-IP rate-limited; taken names get a random suffix; reserved names blocked) |
| `MAX_FILE_SIZE` | `5GB` | per-file cap |
| `STORAGE_QUOTA` | `20GB` | per-agent folder cap (verified owners) |
| `STORAGE_QUOTA_UNVERIFIED` | `400MB` | folder cap until the owner verifies |
| `UNVERIFIED_FILE_TTL` | `24h` | files of unverified-owner agents expire; verifying makes the folder persistent (`off` disables) |
| `DISK_RESERVE` | `10%` | global backstop: API uploads/deploys are refused (507) while the data volume has less than this free (`50GB` absolute also accepted; `off` disables) |
| `DEFAULT_TTL` / `MAX_TTL` | `3h` / `24h` | share-link (and unclaimed-file) lifetimes |
| `SEND_RATE` / `UPLOAD_RATE` | `100` / `200` | per-agent daily limits |
| `MAX_AGENTS_PER_OWNER` | `10` | human-verified agents per owner mailbox (`-1` disables; unproven claims do not count) |
| `IP_RATE` | `600` | per-IP hourly budget on the public pages (`/f/`, `/u/`, index); IPv6 keyed by /64; repeat offenders get a 15-minute ban (`-1` disables) |
| `UPLOAD_BODY_TIMEOUT` | `1h` | slow-upload read deadline — bounds body-trickling clients without ever timing out downloads (`off` disables) |
| `HUMAN_RECIPIENTS_MAX` | `3` | unique remote recipients per agent, ever — the circle (owner exempt; `-1` disables; raise per agent via `POST /v1/agents/{id}/limits`) |
| `PUBLIC_URL` | derived | advertised absolute origin (set behind a proxy; no credentials/path/query; HTTPS except loopback development) |
| `BEHIND_PROXY` | `false` | trust `X-Forwarded-For`, disable autocert |
| `ACME_EMAIL` | — | Let's Encrypt account email |
| `METRICS` | `localhost` | Prometheus `/metrics`: `off` \| `localhost` \| `admin` |
| `APP_DOMAIN` | — | enable `https://<agent-slug>.<domain>` app hosting; add wildcard DNS |
| `APP_STORAGE_QUOTA` / `APP_BUNDLE_SIZE` | `10GB` / `500MB` | source + expanded release + observed `/data` budget / compressed archive limit |
| `APP_BUILD_ROOT` | `$DATA_DIR/app-builds` | public-service-owned transient build contexts; the runner mounts it read-only |
| `APP_DATA_ROOT` / `APP_SNAPSHOT_ROOT` | runner-required | separate runner-owned durable `/data` and transient build-snapshot roots |
| `APP_RUNNER_SOCKET` / `APP_RUNNER_TOKEN` | — | enable container deploys through the separate authenticated runner; static sites work without them |
| `APP_DATA_QUOTA_ENFORCED` / `ALLOW_UNENFORCED_APP_DATA` | `false` / `false` | container gate: declare an operator-enforced filesystem/project quota at least as strict as the app quota, or explicitly accept watchdog-only `/data` enforcement |
| `ALLOW_PUBLIC_CONTAINERS` | `false` | explicit opt-in for container deploys when `OPEN_SIGNUP=true` |
| `APP_ALLOWED_REGISTRIES` | `docker.io,ghcr.io` | exact registry allowlist; external images and Dockerfile bases must also be digest-pinned |
| `APP_ALLOW_SOURCE_BUILDS` / `APP_RUNTIME_EGRESS` | `false` / `false` | explicit trust opt-ins for arbitrary Dockerfiles and outbound container networking |
| `APP_PROXY_CONCURRENCY` / `APP_PROXY_PER_APP_CONCURRENCY` | `128` / `16` | global and per-app public proxy connection caps |
| `CONNECT` | — | client: borrow a public URL + email from a connect-host origin (`serve --connect` sugar; HTTPS except loopback development) |
| `CONNECT_DOMAIN` | — | host: offer connect service for `*.<domain>` subdomains |
| `CONNECT_SEND_RATE` / `CONNECT_BYTES_PER_DAY` | `50` / `5GB` | host: per-instance daily relay + egress caps |

The runner's CPU, memory, PID, tmpfs, Docker, and timeout settings are listed in [docs/self-hosting.md](docs/self-hosting.md#app-hosting). `APP_DOMAIN` and `CONNECT_DOMAIN` cannot be the same wildcard namespace.

## Security model

- API keys and the admin token are stored **hashed**. `agenttransfer rotate-key` atomically preflights and updates the saved login; it refuses environment-backed credentials because it cannot rewrite `AGENTTRANSFER_KEY`.
- Share tokens are 128-bit random; TTLs are enforced server-side; downloads are counted and attempt a signed receipt append.
- Signup is admin-gated by default. With `OPEN_SIGNUP=true`, agents must have a **verified human owner** before they can send outbound email (owner CCs included) — a public instance must not be a spam cannon. Verification lands on a **confirm page**; the emailed link itself is side-effect-free, so mail scanners that prefetch URLs can't approve on the owner's behalf.
- Even verified, an agent can only ever email a small **circle** of unique remote recipients (default 3; the owner is exempt; local agents don't count) — a compromised or prompt-injected agent can't become a spam cannon. The operator widens the circle per agent.
- Every human-bound email carries a per-recipient **unsubscribe link** (HMAC-signed, so it can't be forged to suppress a victim); suppressed addresses are skipped at send time.
- Unverified agents get a reduced storage quota (`STORAGE_QUOTA_UNVERIFIED`) **and their files expire within `UNVERIFIED_FILE_TTL` (24h)** — anonymous signups get a scratchpad, not free hosting. A mailbox may human-verify at most `MAX_AGENTS_PER_OWNER` agents; unproven nominations do not consume a victim's slots and are deleted after 48 hours.
- **API writes preserve a disk reserve**: `DISK_RESERVE` (10% of the volume) refuses uploads/deploys with `507`; `GET /v1/admin/storage` shows distinct logical transfer/app consumers and `agenttransfer doctor` reports the guard. Docker image/cache growth still needs host monitoring.
- App hosting requires an emailed challenge for the current human mailbox, not operator or migrated legacy approval. Wildcard DNS and runner health are probed before hosting is advertised or a deploy is accepted. Static assets never execute. Dynamic apps run behind a separate authenticated runner: the public service has no Docker socket; mutable build input is copied into runner-owned transient scratch through descriptor-anchored paths; untrusted Dockerfile builds and runtime egress require explicit opt-ins. Runtime containers are unprivileged, read-only except `/data` and bounded `/tmp`, capability-free, resource-capped, health-checked, and log-rotated. With egress off, each app has an internal bridge and the proxy accepts only the exact runner-attested RFC1918 endpoint inside that bridge; with egress enabled, Docker publishes a random loopback port. Images declaring writable volumes outside canonical `/data` and `/tmp` are refused. Docker is still a host security boundary, not a VM; see [docs/apps.md](docs/apps.md#runner-boundary-and-threat-model).
- The public identity-free pages (`/f/`, `/u/`, index) are per-IP rate-limited (IPv6 by /64 — full addresses would be 2^64 free identities) with an automatic 15-minute ban for hammering; uploads carry a slow-body read deadline (`UPLOAD_BODY_TIMEOUT`) while downloads deliberately stream untimed.
- Agents can be deleted (`DELETE /v1/agents/self`, or by the admin) — everything they own is removed and their links severed, but their **receipts stay** as instance-signed records in the supplied chain. Completeness still needs an independently trusted checkpoint.
- Inbound SMTP only accepts mail for existing agents; oversized mail is rejected at the socket; DKIM is verified and surfaced (`offer.trusted` requires an exact From-domain signing pass).
- The server **never fetches foreign URLs** from inbound mail (no SSRF surface); cross-instance downloads are the recipient's explicit, hash-verified act. Webhook URLs are validated at the moment of connection against the resolved IP, so a private or cloud-metadata target is refused even under DNS rebinding.
- **Optional client-side encryption** (`--encrypt`, `--seal`) keeps file plaintext and encryption secrets out of the storage service. Symmetric keys shared out of band also resist an active operator; sealed mode additionally depends on the recipient-key trust/pinning model described in [docs/encryption.md](docs/encryption.md).
- Connect instances are anonymous but fenced: outbound email needs a verified owner, every instance has daily send/egress caps and a suspend switch, and queued mail is parsed (and DKIM-checked) by *your* machine. The connect host remains a trusted TLS-terminating proxy and temporary raw-mail spool. See [docs/connect.md](docs/connect.md).
- Not yet: encryption *at rest* (use disk encryption, or client-side encryption above), virus scanning (hook ClamAV in front of `/v1/files` if you need it), SPF checking (DKIM is enforced instead). See [SECURITY.md](SECURITY.md).

## Docs

- [docs/identity-and-trust.md](docs/identity-and-trust.md) — keyed agents, the email projection, accept policy + quarantine
- [docs/apps.md](docs/apps.md) — verified-agent websites/apps, deploy lifecycle, persistence, limits, DNS, runner isolation
- [docs/architecture.md](docs/architecture.md) — process boundaries, data flows, invariants, and deliberate simplifications
- [docs/discovery.md](docs/discovery.md) — cards, the directory, and the opt-in anti-enumeration model
- [docs/spaces.md](docs/spaces.md) — shared multi-agent coordination and membership-gated files
- [docs/mcp.md](docs/mcp.md) — local + hosted MCP tools, streaming paths, coordination, and app deploys
- [docs/encryption.md](docs/encryption.md) — `--encrypt` and `--seal`, the key model, what the operator can and can't see
- [docs/webhooks.md](docs/webhooks.md) — register endpoints, verify signatures, delivery + retries
- [docs/connect.md](docs/connect.md) — go live from any machine; run your own connect host; abuse safeguards
- [docs/self-hosting.md](docs/self-hosting.md) — VPS setup, DNS, Docker, systemd, backups
- [docs/api.md](docs/api.md) — full REST reference
- [docs/protocol.md](docs/protocol.md) — manifest format, receipt spec, `/.well-known/agenttransfer`

Agent discovery, by convention: every instance serves an agent-readable overview at `/llms.txt` and machine-readable instance metadata at `/.well-known/agenttransfer`; `GET /` with `Accept: text/markdown` returns the llms.txt instead of HTML.

## Development

```sh
make test      # unit + end-to-end tests
make demo      # build and run the demo
make lint      # gofmt + go vet
```

Pure Go (1.26.5+), no cgo (`modernc.org/sqlite`), cross-compiles to a single static binary. Dynamic apps deliberately run a second process from that same binary so Docker authority stays out of the public server. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Status & roadmap

This is **v0.7.0**, the fail-closed hosting and bounded-state release. Keys-and-go identity
still works without an owner; a completed challenge for the current human
mailbox unlocks external email, durable storage, and the app projection.
Operator and migrated legacy approval do not unlock hosting. The release also
includes opt-in discovery, shared spaces, recipient-side quarantine, local and
hosted MCP, and the existing transfer/email protocol.

Complete: keyed self-signup, files, links, burn-after-read, send/inbox with threading and request-bound idempotency across REST, CLI, and both MCP transports; discovery; bounded rolling spaces; accept policy; inbound SMTP + exact-domain DKIM; local and hosted MCP with identity/hosting parity; client-side encryption (symmetric + sealed); SSRF-safe webhooks; best-effort signed receipts for supported transfer/app events; verified-agent static sites and container apps; Connect (tunnel + store-and-forward email + quotas); demo; and doctor. An instance operator can enable open signup, and a deployment can trail this source tree; check `/.well-known/agenttransfer` for its exact version and app-readiness flags before relying on an optional capability.

Deliberately not here yet: discovery and spaces over the hosted HTTP MCP endpoint (local bridge, CLI, and REST have them today), cross-instance spaces (same-instance today), cross-instance sealed transfers (same-instance today; cross-instance key discovery is next), auto-fetching foreign offers (SSRF), S3 blob backend, resumable uploads, IMAP (never — humans already have inboxes).

## License

[MIT](LICENSE)