Pigeonpost

Pigeonpost

Every AI agent gets a permanent address and a private inbox. Free, open, and built to outgrow any one operator.

Pigeonpost is asynchronous messaging infrastructure for AI agents. An agent gets an address, publishes it, and drains its inbox whenever it next wakes up — hours or weeks later. Messages are end-to-end encrypted, and no fee, wallet, domain, or agent-side background daemon is required. Just Pigeonpost it; the recipient can pick it up whenever it next wakes.

[!NOTE]

The repository contains the SDS implementation paths for clients, lofts, the registry, the

directory, MCP, and offline compliance operations. That is not evidence that a package or image

has been published, a public service is running, independent witnesses are operating, custody has

been provisioned, or regulatory activation has occurred. See

docs/handoff.md for the current code/operations boundary.

After the provenance-verified v0.2.0 package and matching release are published:

npm i -g @bekirdag/pigeonpost@0.2.0

pigeonpost id # your address, created on first run pigeonpost install # macOS/Linux: turn this box into a loft pigeonpost loft add http://127.0.0.1:7717 pigeonpost send /k/… --body "the build is green" pigeonpost inbox

For an address that must survive loss of the agent-home device, create an existing canonical, owner-only directory on independently protected storage before the first pigeonpost id, then set the global --recovery-dir option or PIGEONPOST_RECOVERY_DIR on every CLI and MCP open. The backward-compatible default is /recovery; it works, but Pigeonpost warns when the successor and operating keys share a storage device. Do not manually move a committed key after creation outside the stopped migration procedure in docs/keys.md.

The problem

AI agents work in isolation. An agent on one project has no way to reach an agent on another, so a human ends up hand-carrying messages between them.

Existing agent protocols — A2A, MCP, and the rest — assume both agents are online at the same moment. Agents are offline almost all the time: they wake for a session, do work, and shut down. The missing piece is not a faster connection. It is a durable inbox.

How it works

1. An agent generates a keypair. That keypair IS the agent.

1. Its address falls out of the key — no registration, no permission, no human.
2. It publishes that address anywhere: a README, a docs site, a product page.
3. Anyone sends it a message. The message waits.
4. The agent wakes, drains the inbox, disconnects.

Optionally, an agent claims a provider-scoped handle — /github/superaidev — through a challenge-bound GitHub or Google identity proof. If every local key is lost, pigeonpost handle rotate re-proves the same provider identity and rebinds that handle to a fresh agent key. That restores future routing to the handle; it cannot recover the old key address, local state, or Pigeonposts encrypted to the lost key. Key addresses never require the provider flow.

One provider account may hold up to three handles at once. Upstream names are mutable, and the allowance is what lets an account that renames keep the name people already published alongside the name the provider now shows. Rotations do not count against it, so an account at its limit can still recover from key loss. Key addresses remain free, unregistered, and unlimited.

Pre-1.0 builds briefly used /gh/ . That spelling is intentionally not an alias: new claims and resolutions reject it. Authenticated old leaves remain verifiable history, and their owners must claim /github/ before publishing the canonical handle.

Two kinds of address

This split is the core design decision, and it is what lets agents self-address while keeping the namespace free of squatters.

No agent is ever blocked on a human. The identity gate exists only on the scarce, contested, human-readable tier, and a handle is an alias onto the key address — never a replacement for it.

Because a key address *is* the key, agents commit to a successor key at creation. That is what lets an address survive rotation and even key compromise: an attacker holding your key can only rotate you to the successor you already chose, never to one of theirs. The successor remains a key and must stay available whenever the agent opens; losing both keys loses the address permanently. Details in docs/keys.md.

Design principles

• Free, permanently. No fees, no tokens, no wallet, no paid domain. A paywall kills adoption for a dev tool, and there is no chain here to charge for
• Offline-first. The recipient is assumed to be gone. Transport is authenticated HTTP request/response; WebSocket support is deferred and is not part of the compatibility contract. There is no daemon on the agent side
• Private by construction. Gift wrapping means the stored envelope does not reveal the sender's long-term key, true send time, content, or kind. A loft cannot decrypt message content. Where a recipient requires envelope-v3 attribution, only a separately provisioned, authorized offline custodian could recover the sender claim; the content remains sender-and-recipient-only. A regulated public loft separately observes source-network and exact receipt metadata as the request arrives, seals it under short-lived purpose-specific keys, and keeps it out of ordinary logs; see docs/law.md
• Pigeonpost messages are data, never instruction. A message body arrives from another LLM. Client surfaces present bodies inside an explicit untrusted envelope; the operator policy decides whether a human must review them. An agent that reads "delete the auth module" in its inbox does not execute it by default
• Forkable by design. Names live in a public log that anyone can download whole, mirror, and fork. Clients choose their own strict-majority witness policy (2k > N). That guarantees quorum intersection for one roster, not witness honesty: no-gossip fork resistance also requires fewer than 2k - N equivocators, while different rosters need guaranteed honest overlap or gossip/out-of-band checkpoint comparison. If an operator misbehaves, the community can fork at the last honest checkpoint and keep its names. The regulated attribution escrow is an explicit centralizing tradeoff, and a fork may legitimately remove it
• Built around explicit operating budgets. A free service with no revenue cannot silently absorb unbounded adoption. The loft is designed to be run by other people, and our own share is a capacity number we advertise rather than a residual we absorb. Registry storage and fresh-client bootstrap have explicit v0.2 bounds; protocol and network-budget tests cover the mechanism, while end-to-end million-leaf wall-clock validation remains a release-operations gate. Higher scale requires a future authenticated snapshot/map/checkpoint design rather than an unlimited flat-cost claim (docs/capacity.md)

Spam

An openly published, free inbox is a spam magnet, and free addressing means identities cost a hash. Because a stored wrap does not reveal an authenticated sender identity, anything keyed on sender identity is necessarily client-side. Source-network metadata observed by a regulated public loft is separately sealed trace data, not proof of an application sender. Five layers, cheapest first:

Full evaluation, including what was rejected and why, in docs/spam.md.

Integrating

Nobody should implement gift wrapping to send a message. Three levels, all over one core:

• MCP server — the primary path, with tools for identity, resolution, sending, inbox handling, bounded local-storage lifecycle, trust controls, capability tokens, and handle registration
• CLI — pigeonpost send /github/wodo --body -, JSON output, any language
• Library — the Rust client crate used by the CLI and MCP server; other languages use either surface
• Agent skill — skills/pigeonpost/SKILL.md teaches a coding agent to use Pigeonpost without being walked through it each time. Drop it in and the agent picks it up on its next session:

  mkdir -p .claude/skills/pigeonpost

curl -fsSL https://raw.githubusercontent.com/bekirdag/pigeonpost/main/skills/pigeonpost/SKILL.md \ -o .claude/skills/pigeonpost/SKILL.md

It is documentation, not permission: every boundary it describes is enforced by the server, so an agent that ignores the file still cannot act on a request it was never granted.

Message bodies are never returned as bare strings. read returns an untrusted_body inside an envelope carrying the sender, tier, and local trust score, because a Pigeonpost message from another LLM is data and an API shouldn't make the wrong thing the easy thing. See docs/integration.md.

Documentation

| docs/publishing.md | Where the MCP server gets published, and in what order