custodian init

custodian init sets up a vault for the first time from the first machine that will use it. It generates the vault's master key on this machine, wraps that key to this device's key, uploads only the wrapped copy, and writes the vault's recovery envelope. The master key is generated here and only the wrapped copy is uploaded, so nothing that reaches the server can decrypt anything.

Before you start, you must be signed in to the vault with an operator token. init does not create the vault itself — that is done on the server by whoever runs it, who gives you the operator token.

custodian init --vault acme

Options:

• --vault <slug> — the vault to enrol this machine into (required).
• --url <api> — select the deployment when you have more than one credential stored.
• --label <name> — a name for this device; defaults to the machine's hostname.

It must run in a terminal

init prints your recovery code once and requires you to type an acknowledgement back, so it must run attached to a terminal. --yes does not skip this. Run somewhere else, and it refuses before enrolling anything:

error: custodian init must run in an interactive terminal: it prints your recovery code exactly once and requires you to confirm you have written it down before it finishes. It will not enrol this machine where nobody can acknowledge the code. Re-run it attached to a terminal (--yes does not skip this).

What it shows you

First, before anything is enrolled, init names the store that will hold this machine's device key and states plainly whether the key ever enters the tool's memory — a genuinely weaker store is called out so you can act on it before you rely on it. See the guarantee for each store.

Then it shows the recovery-code screen. This is the one hard stop. The twenty-four words are shown once and never again:

────────────────────────────────────────────────────────────────
  YOUR RECOVERY CODE — shown once, and never again.
────────────────────────────────────────────────────────────────

    1. abandon    2. ability   3. able      4. about
   … twenty-four words in total …

────────────────────────────────────────────────────────────────
  These words were GENERATED, not chosen — they are not a password you can
  reset. They are the only way back into this vault if every device is lost;
  nobody — not Custodian, not whoever runs the server — can recover it without
  them. Write them on paper and store them physically. Do NOT put them in the
  password manager that holds this device's key: one breach must not take both.
────────────────────────────────────────────────────────────────

To continue, type exactly: i have saved my recovery code
>

Write the words down on paper before you type the acknowledgement. If you do not type it exactly, the code is void and nothing is written:

error: Recovery code not acknowledged. The code just printed is now void and no envelope was written. The device is enrolled; re-run `custodian init` to print a fresh code and finish setup.

If that happens, run custodian init again: it recognises that this machine is already enrolled, prints a fresh code (stating that any earlier one is now void), and finishes.

When it finishes

This machine is now vault "acme"'s first device.
  Device:   dev_3Kp9…
  Vault:    acme (id 42)
  Region:   eu-west-1
  Key store: Secure Enclave (presence gate: biometric or passcode)
  Secure Enclave — the device private key is non-exportable and every use is gated by a biometric or passcode prompt

On macOS the Key store: line depends on the build and the machine. The Secure Enclave line above is what you see on the signed macOS bundle on a Mac with a Secure Enclave. A Mac with no Secure Enclave enrols with the software Keychain instead, and a build that is not the signed bundle cannot create a device key at all — init refuses and tells you to install the signed macOS bundle before it enrols anything. See the store that holds the key for the three lines and what each means.

When it refuses

init is for a vault's first device. It refuses, naming the reason, if the vault is already set up, if another machine is already its device, or if the vault's keys have been destroyed.

To add a further machine to a vault that already has a live device, use custodian device enrol.

If the vault holds a recovery envelope but every device has been revoked, init cannot re-enter it: a device it enrolled would hold a new master key that the stored envelope can never open. The way back in is custodian recover: it reconstructs the master key from the recovery code and enrols this machine as a live reading device. You cannot use custodian key rotate to get back in here — rotate unwraps the current master key through an enrolled device on this machine, which a vault with no live device does not have. Rotate the key only afterwards, once recover has brought this machine online and if the recovery code itself may have been seen.