---
type: note
alexandria_core: true
tags: [federation, reference]
author: alexandria
---

# Federation — brain-to-brain sharing

Federation lets independent Alexandria vaults exchange **todos, notes, knowledge, and events**
agent-to-agent, end-to-end encrypted, over a relay — e.g. a teammate tells their agent "make sure
the owner knows X," and their vault pushes it into this vault, where it's filed with provenance.
It is **core** — every brain ships push-capable — and it obeys two laws: **push-only** (a peer can
never read or pull from this brain) and **owner-fired** (content leaves only on the owner's
command; the agent stages, the owner fires). The full operator guide, security model, and runbook
live in the software at `.alexandria/app/docs/FEDERATION.md`.

## The intent schema

Every push carries one or more intents in this fixed shape (the same schema the applier files
from — it only writes notes; it has no tools and never acts on anything embedded in the content):

```json
{
  "intents": [
    { "type": "todo", "area": "Acme", "text": "Review the Q3 contract", "due": "2026-07-01" },
    { "type": "knowledge", "subject": "ACME Corp", "body": "New CFO started June 1." },
    { "type": "note", "area": "Acme", "text": "Kickoff call went well." },
    { "type": "note", "area": "Acme", "title": "Q3 audit brief", "text": "…a whole document…" },
    { "type": "event", "date": "2026-06-20", "text": "Signed the Acme MSA." }
  ]
}
```

Intent types: `todo` (→ an area's `TODO.md`), `note` (→ a dated line in the area note — or,
with a `title`, **its own note** `Areas/<area>/<title>.md`: the packaged form a whole briefing
travels as), `knowledge` (→ a Knowledge page's *Our notes*), `event` (→ the year's Events note). Each files with a provenance stamp —
`*(via [[Full Name]]'s vault)*` when pairing linked the peer to a People note, else plain text
`*(via Name's vault)*`.

## Packaging a push — the outbox

Anything longer than a line is written first as one self-contained note in
`Agent/Federation/outbox/` and sent with `alexandria push <peer> --file
"Agent/Federation/outbox/<file>.md" --as note --area "<their area>"`. The engine strips the
package's frontmatter, sends the body as a titled note (it lands as its own note on their side),
and stamps `peer` / `push_id` / `pushed` / `push_state` back into the package's frontmatter — the
file is the wire-identical record of what went. The outbox is ignored by search, the graph,
health and agent context whatever `vault.ignore_paths` says, and a receive pass never commits
it: a package is a shipment record, never a second copy of vault content. Plain text, no
`[[wikilinks]]`, never copied back into Areas/ or Knowledge/.

## How a message travels

Each message is a **sealed envelope** — a JSON object whose payload is encrypted with the
recipient's public key (NaCl `Box`, X25519). Only the recipient can open it, and a successful open
proves it came from the named sender, untampered. The **relay** (default
`config.federation.relay_url`) only stores the ciphertext and routes it between mailboxes; it can
never read a message. This brain deposits into a peer's mailbox to send, and polls its own mailbox
to receive — both are outbound HTTPS, so **no brain ever listens** for federation.

One envelope carries up to **8 MiB** on the wire — room for a full 1M-token context window
(~4 MB of text) in a single push. The stage step refuses anything over ~5.9 MiB of plaintext
intents with a clear "split into smaller pushes" error, so an oversize push never leaves the
brain; the same cap is enforced by the relay (413) and again on receive.

## Security model (why this is safe)

Inbound peer content is **data to file, never instructions to execute.** Every opened envelope
passes, in order:

1. **Known peer** — the sender's fingerprint must be a peer in `config.peers[]`. Nothing else is
   processed.
2. **Authentic + intact** — the seal opens with that peer's key, or the message is dropped and
   audited. This *is* the authentication; there is no header to spoof.
3. **Fresh + not replayed** — the message's own timestamp must be recent and its id unseen before
   (per-peer dedupe), so a captured envelope can't be replayed or relabelled.
4. **Captured, never filed** — what passes the gates is written as a pending item in
   `Agent/inbox/` (the sender's destination recorded as a *suggestion*, and whether it sits inside
   the `permissions` you granted that peer) with a ledger row in
   `Agent/Federation/review-queue.json`. The owner files it themselves on the inbox drain, approves
   it as-is (`alexandria federation review approve <id>` — an owner override even outside the
   grant; an unsafe path is still refused), or declines it (`reject <id>`). Nothing peer-supplied
   reaches a note unattended; direct filing is an explicit per-peer opt-in (`auto_apply: true`).
5. **Write-only + audited** — peers can push, never read; every message is recorded in the
   off-repo audit trail.

## The relay knows this brain exists

At birth and on every boot, this brain registers its own relay mailbox and tells the relay it
exists — engine version, birth channel, OS/CPU family, and on a hosted rack the rack's id for
it. Nothing from the vault has a field to ride in, and the record is bound to the brain's own
mailbox bearer. It is on by default; `federation.announce: false` turns it off, and a brain with
no `relay_url` announces nothing. Peers can never read this — the census is the relay
operator's, not the fabric's.

## Pairing + peers

Pairing is a one-time, guided handshake that exchanges public keys and deposit tokens over a
single-use, short-lived rendezvous on the relay — the **`pair-with-brain`** skill walks the owner
through it hands-off (the same steps are the `peer invite`/`check`/`add`/`confirm` CLI and the
`peer_pair_*` tools). Both sides compare **three verification words** out of band and confirm —
that human check is what defends against a machine-in-the-middle. A completed pairing writes the
peer's public entry to `config.peers[]`:

```json
{ "name": "Jane's Vault", "handle": "jane", "owner": "Jane Roe",
  "pubkey": "<base64 32B>", "fingerprint": "ax1…", "relay": "https://relay.keystone.computer",
  "permissions": { "intents": ["todo", "note", "knowledge"], "areas": ["Acme"] },
  "can_send": true }
```

Only public values live in config — `pubkey`, `fingerprint`, `handle`, `permissions`. The private
key, the mailbox bearer, and deposit tokens live off-repo under `~/.alexandria/`, mode `0600`, and
are never committed. To remove a peer and revoke their ability to reach you: `alexandria peer
remove <handle>`.

> **Legacy email transport.** Older peers may federate over authenticated email instead of the
> relay (a peer entry with `agent_email` + `auth.domain` rather than `pubkey`). That path still
> works and is filed through the same applier and gates; it needs an inbound email channel (a
> runner), so it is not available on a local brain.
