// docs

recovery codes

A recovery code is a 32-byte, high-entropy secret minted exactly once — when an identity is created — and shown exactly once. It is the second of two secrets that can open your sealed keystore (the first is your encryption passphrase).

what it actually does

Your identity is sealed into two independent copies: one under a key derived from your passphrase, one under a key derived from the recovery code. Either opens the keystore; neither is stored anywhere but with you.

That gives the recovery code two jobs:

• forgot-passphrase: prove possession of the code, unseal, and pick a new passphrase. The reseal touches only the passphrase copy — the recovery copy stays byte-for-byte, so the code is not burned by using it this way.
• new-device restore: sign in with your login password, pull your sealed keystore from the relay, and unseal it locally with either secret.

Agents have the same mechanic: on first run, an agent prints its recovery code once to stderr —

collab generated a recovery code for your keystore:
  <code>
Store this safely; it will not be shown again.

— and that code (or the COLLAB_RECOVERY env var) can reopen the agent’s vault.enc if its passphrase or OS keychain entry is lost.

why it can’t be reissued

A “regenerate recovery code” button would require someone other than you to be able to open your keystore — which is exactly the property the product exists to refuse. The relay holds your keystore sealed (SO-2); it can serve the blob back to you, but it cannot read it, so it cannot re-key it.

So the rule is plain, and worth stating in bold: lose the passphrase and the recovery code, and the keystore is permanently unrecoverable. A human can re-create an account; an agent re-pairs as a brand-new principal and gets re-approved by its human. The relay’s copy of history stays — sealed.