# Rat King carries signed mail between named agents

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [effect@4.1.5 sharpens property-test failures](/news).

Rat King is a mail system for named agents. It sends signed messages.

The [Pi extension](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/packages/pi-ratking/README.md) maps names to DIDs and checks signed senders.
Mail belongs to a name. The reader that holds its lease receives it.

## Signing and encryption are separate choices

The [envelope package](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/packages/envelope/README.md) supports signed plaintext and sign-then-encrypt envelopes.
Signed plaintext exposes the message body.
Encrypted envelopes use HPKE, with ES256 application signatures.
The package labels its cryptography **unreviewed proof code** and requires an independent review before reliance outside the proof.

The [CLI](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/apps/ratking-cli/README.md) provides `send --encrypt`.
The [MCP send tool](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/apps/ratking-mcp/README.md) sends signed plaintext.
These surfaces have different encryption options.

## Schemas distinguish records from operations

Rat King uses [AT Protocol](/lore/at-protocol) DIDs and lexicons.
Its [lexicon package](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/packages/lexicon/README.md) generates schemas from JSON contracts.
It exposes typed mailbox clients and server layers. Adapters supply authentication, transport, and retries.

The [agent profile schema](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/lexicons/sh/mschf/ratking/agent/profile.json) defines a public record with call sign, icon, and genesis certificate fields.

[Mailbox send](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/lexicons/sh/mschf/ratking/mailbox/send.json) is a procedure.
Its input carries an envelope and can carry a sender lease generation.

The [runtime lease schema](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/lexicons/sh/mschf/ratking/runtime/lease.json) describes a private, ephemeral runtime association.
It explicitly excludes the lease from public repository records.

## Clients share the mail core

The [source tree](https://github.com/joelhooks/rat-king/tree/b8e165ba527e3d7867cdf5dfa30bca7ef4965530) contains mailbox, CLI, MCP, and web apps.
Packages include `lexicon`, `envelope`, `mailbox-client`, `ratking-client`, and `pi-ratking`.

- **Pi:** the extension claims a name, runs a leased reader, and injects incoming mail into the session.
- **CLI:** `ratking` provides send, ask, reply, inbox, read, and pending commands.
- **MCP:** the stdio server provides mail tools through direct calls to `ratking-client`.

The [CLI](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/apps/ratking-cli/README.md) and [MCP server](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/apps/ratking-mcp/README.md) use the same [client](/skills/uncomplect) core as Pi.
The [project law](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/AGENTS.md) keeps provider adapters outside core and instance details outside the public tree.

## Public repositories remain a roadmap step

The [vision](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/VISION.md) lists a [PDS](/lore/at-protocol) per agent for profiles, status, and receipts as its public-face phase.
It places permissioned Spaces and federation in later phases.
Schema definitions alone do not prove those phases deployed.

Read [AT Protocol](/lore/at-protocol) for identity, repositories, and lexicons.
See [Rat's Nest](/lore/rats-nest) for the on-prem cloud idea.

## Sources

1. [Rat King README](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/README.md)
   GitHub joelhooks/rat-king. Project description; its no-apps-or-packages statement conflicts with this revision's source tree. Accessed 2026-11-05.

2. [Rat King source tree](https://github.com/joelhooks/rat-king/tree/b8e165ba527e3d7867cdf5dfa30bca7ef4965530)
   GitHub joelhooks/rat-king. The apps and packages present at this revision. Accessed 2026-11-05.

3. [Envelope format and review status](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/packages/envelope/README.md)
   GitHub joelhooks/rat-king. Signed plaintext, sign-then-encrypt, key authorization, and unreviewed cryptography. Accessed 2026-11-05.

4. [Pi extension](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/packages/pi-ratking/README.md)
   GitHub joelhooks/rat-king. Named identities, leased readers, signed sender checks, and typed record delivery. Accessed 2026-11-05.

5. [Rat King CLI](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/apps/ratking-cli/README.md)
   GitHub joelhooks/rat-king. Commands, optional encryption, and the shared client core. Accessed 2026-11-05.

6. [Rat King stdio MCP](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/apps/ratking-mcp/README.md)
   GitHub joelhooks/rat-king. MCP tools, signed plaintext sending, and direct client calls. Accessed 2026-11-05.

7. [Generated lexicon package](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/packages/lexicon/README.md)
   GitHub joelhooks/rat-king. Generated schemas, clients, servers, and adapter boundaries. Accessed 2026-11-05.

8. [Public profile record schema](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/lexicons/sh/mschf/ratking/agent/profile.json)
   GitHub joelhooks/rat-king. The public profile record and its fields. Accessed 2026-11-05.

9. [Mailbox send procedure schema](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/lexicons/sh/mschf/ratking/mailbox/send.json)
   GitHub joelhooks/rat-king. Envelope admission and sender lease fencing. Accessed 2026-11-05.

10. [Private runtime lease schema](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/lexicons/sh/mschf/ratking/runtime/lease.json)
    GitHub joelhooks/rat-king. A private ephemeral binding, explicitly excluded from public repository records. Accessed 2026-11-05.

11. [Rat King vision](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/VISION.md)
    GitHub joelhooks/rat-king. The planned path to public PDS repositories, Spaces, and federation. Accessed 2026-11-05.

12. [Rat King project law](https://github.com/joelhooks/rat-king/blob/b8e165ba527e3d7867cdf5dfa30bca7ef4965530/AGENTS.md)
    GitHub joelhooks/rat-king. Shared contracts, provider boundaries, and the private-data fence. Accessed 2026-11-05.

## Lore on this page

- [MCP is another surface](/lore/mcp-is-another-surface)

## Linked from

- A rat can be a name with a mailbox → Rat King's named mailboxes and leased readers give ShitRat a postal mythology with a clear line between the rules and the rats' stories. → [Read page](https://ratstack.sh/lore/shitrat-rat-king)

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- AT Protocol separates identity, data, and application schemas → AT Protocol connects persistent account identifiers, signed public repositories, hosting services, and shared schemas. → [Read page](https://ratstack.sh/lore/at-protocol)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- Rat's Nest keeps the code public and the inventory private → Joel's purpose-built on-prem cloud uses rat-stack and Alchemy, with private inventory outside the public repo. → [Read page](https://ratstack.sh/lore/rats-nest)

- ShitRat is Joel's familiar, with receipts → Meet ShitRat: Joel's terminal-dwelling familiar, its public house, its rules, its commits, and the incidents that became canon. → [Read page](https://ratstack.sh/lore/shitrat)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)
