Federation
Cooperate with an operator who shares no key with you, while each kernel admits the other's work under its own policy.
On this page
Two organizations share no administrator, database, or signing key, and neither should have to trust the other's kernel. Federation makes their cooperation a relationship between two sovereign kernels: each pins the other's key from a partner card, a treaty names the actions they cooperate on, and every action is admitted by the kernel that serves it, under that kernel's own policy.
Adding the card pins their kernel key
chio partner add partner-card.json --name partner reads the card the partner sent: its org DID, did:chio:z6MkpA7…c2T, its trust-control URL, its authority key history, its receipt-signer keys, and its status resolve URL. Adding it pins the partner's kernel key, 9b07…d31c, in your trust store. Each operator adds the other's card, so each kernel keeps its own pin. Peer pins.
chio partner add reads it: the five fields it carries and the kernel key adding it pins. The DID and key are the Quickstart's illustrative values. Treaty terms, transport, and the conformance evidence the handshake carries are left out.Peer pinsA verified identity or a valid signature answers only part of the question. When your service delegates a review to a partner, the partner needs to know who issued the request, what authority was delegated, and which of its own rules still apply, and you need evidence you can attribute to the partner you expected. A peer relationship binds its two operators only: accepting a peer authorizes none of that peer's partners, as the three-operator topology shows.
An identity names a key, and adding the partner's card is your decision to trust it
A Chio identity encodes an Ed25519 public key in its DID, so any verifier resolves it locally with no shared registry. That tells you which key the identity controls, not whether the key belongs to your intended partner.
The partner card carries the organization's DID, its trust-control URL, its authority key history, its receipt-signer keys, and its status resolve URL. Adding it, from a card you received over an authenticated channel, pins the partner's kernel key.
chio partner add partner-card.json --name partnerpartner did:chio:z6MkpA7…c2T, named partner kernel 9b07…d31c, pinned from its card transport https, kernel.halden.example, mTLS
The handshake then signs a challenge that binds both kernel ids, a fresh nonce, and the time, verifies it against the pin, and records the peer's conformance tier and rotation deadline. An unexpected key stops with UnexpectedPeerKey before any peer state is written, and the transport or host consumes each challenge once. Rotation extends the key history without an outage, so receipts signed before a rotation still verify offline. Issuer-signed lifecycle status is pulled from the status resolve URL and kept for its TTL, and a stale status fails closed.
Read more in Peer Handshake.
A treaty names the shared actions, and each door admits under its own policy
Each kernel intersects both operators' governance ladders for a treaty action, so the stricter requirement wins, and a co-sign action needs both signatures. A grant issued to a partner's agents narrows as they delegate among themselves. Federated grants require a DPoP proof of possession at your door, so a copied grant carries no authority, and revoking a treaty ends every grant issued under it, including delegated ones.
Evidence flows back with its origin intact: a partner imports a signed, bounded slice of your receipts and verifies it offline, and an imported reputation record stays attributed to its issuer, weighed under the receiver's policy. Every crossing runs over HTTPS with mutual TLS or signed bodies by default, and iroh is an optional lane through self-hosted relays for signals, revocation, and co-signing. An enterprise identity provider's principals become stable Chio subjects at the same boundary.
Read more in Treaties and Cross-Operator Delegation.
Seven groups of pages describe one boundary
Each group is a separate contract. A successful handshake authorizes no tool by itself, and importing a reputation record never turns it into native local truth.
- Peer Trust. Who the peer is and how its key is pinned: Federation Model, Operator Identity & Key Bindings, Peer Handshake, Peer Pins & Trust Bundles, and the Two-Org Worked Example.
- Treaties & Admission. What the relationship permits before any action: Treaties, Trust Activation Exchange, Open Admission & Stake, and Quorum & Anti-Eclipse.
- Authority. What crosses the boundary carrying a signature: Federation Authority, Cross-Operator Delegation, Revocation Oracle, and Revocation Checkpoints.
- Evidence & Reputation. What flows back and how the receiver weighs it: Share Evidence with a Partner, Receipt Lineage & Buyer Packets, and Reputation Clearing.
- Transport. How bytes move between admitted endpoints: Iroh Transport, Transport Directory, Transport Lanes, and Limits & Backpressure.
- Enterprise Identity. The people and workloads behind bearer tokens: Federate Enterprise Identity and Provider Registry & SCIM.
- Operations & Assurance. Running it, diagnosing it, and what is proved: Operate a Federation, Federation Refusal Codes, Federation Assurance, and the Evidence Exchange Walkthrough.
Federate when the other side controls its own trust decisions
Several nodes run by one organization start from shared control state or cluster coordination, and several agents in one application start from ordinary capability delegation. A cross-operator swarm uses federation for the standing trust relationship and graph authority for the delegated work. Compliance evidence matters even for a single node and needs no federation; the mappings that cite federation evidence live in Security under Assurance.
One download builds every federation example on this machine
The Rust project holds the complete producers, receivers, host configuration, and local evidence workflows the federation pages run. Download it, unpack it, and run the first program from federation-guide/.
mkdir federation-lab
cd federation-lab
curl --fail --location https://www.chio.computer/examples/federation-guide.zip \
--output federation-guide.zip
unzip federation-guide.zip
cd federation-guide
cargo run --locked --bin handshakepinned peer: accepted; challenge consumed same challenge: refused by receiving host same identity with another key: refused expired handshake: refused
You should see the peer pinned and its challenge consumed, then three refusals. The first build compiles the kernel and its dependencies, and later programs reuse that build. Cargo fetches the pinned public Chio crates, so no source checkout is needed beside the project.
Before you begin
Install Git, curl, unzip, Rust through rustup, and a C or C++ build toolchain. The project pins Rust 1.94.1 and a Cargo lockfile. The CLI workflows also use the chio CLI and jq. Run every command from federation-guide/ unless a page switches into the source checkout.
Each program creates a fresh run directory and refuses to overwrite an existing one; to repeat a workflow, move the previous run directory aside. Keys are generated locally, approval and revocation stores live in the process, and receipt databases persist the captured run. The programs run both operators on one machine; they provision no external organization, assess no production deployment, and execute no payment. Read the boundary beneath each result before adopting its host code.
Source checkout for the transport examples
Fetch the transport examples
The iroh transport examples build from the public Chio source repository, at the revision their captured output came from. Fetch it beside the downloaded project, from federation-guide/:
git clone https://github.com/backbay-labs/chio.git ../chio-source
git -C ../chio-source checkout 5b8bec41d32f3838b880576fe6123c983ecebf8dDownload the complete project or read its build and workflow instructions.
Next: connect a peer
Establish federation · 1 of 7
NextPeer Handshake