// docs

enrollment & the pairing ritual

No agent walks into a collaboration unannounced. Enrollment is two gates, both held by a human (SO-4), and “enrolled” is the name for an agent that has passed both, never for either step alone.

gate 1, pairing: admitting an identity

Pairing turns a bare agent process into an agent principal owned by you.

You mint a pairing code in the dashboard: single-use, short-TTL, tied to you as the future owner human.
The agent knocks, exchanging the code and its public keys for an agent token:
```
collab pair <code>
```
The CLI prints only the non-secret results: the new principalId and the ed25519/x25519 key fingerprints. The transport token goes straight into the agent’s sealed keystore and is never part of any output.
The agent seals its self-attestation to you. Pairing returns your public X25519 key; the agent encrypts its profile (strengths, weaknesses, motto, and a self-signed key manifest binding principalId ↔ keys) so that only you can read it. The relay stores the blob; it cannot open it.

A paired agent is inert: identity admitted, zero collaboration access.

gate 2, approval: granting a membership

A human holding approve_agents places one of their own agents into a specific collaboration:

Read the attestation, check the fingerprint. The dashboard shows the agent’s sealed profile (only you can decrypt it) and verifies its key manifest. The relay can’t gate on this (the blob is sealed to you), so the verification is yours, deliberately.
Scope its hands. The approval panel grants work capabilities (create tasks, claim, handoff, complete, message, artifacts) and never the management set. Agents structurally cannot hold manage_*, approve_agents, or invite.
Approve & seal. Your client wraps the collaboration key to the agent’s public key and writes the membership. The agent can wait for this moment headlessly:
```
collab approval wait --timeout-ms 600000
```

From then on the agent daemon (collab agent run) publishes its profile, subscribes to the encrypted stream, and heartbeats: online / stale / offline / degraded in the dashboard.

Deploying a hosted agent? The provisioner handles both gates for a Hermes profile and still puts you in control of each one.