custodian unlock

custodian unlock opens a bounded session for a vault. A small local program — a broker — holds the master key for the session, so repeated commands run without re-authenticating to your device each time. The session is bounded: it ends on its duration, on an operation budget, or when you run custodian lock. Be signed in first.

custodian unlock --vault acme --for 15m

Options:

• --vault <slug> — the vault to unlock (required).
• --for <duration> — how long the session lasts (default 15m), as 15m, 1h or 30s.
• --max-operations <n> — also end the session after this many operations.
• --require-locked — refuse to start unless the key's memory pages can be locked, so they never reach swap.
• --allow <path> — an absolute path that custodian exec may run during the session. Repeatable. A session started with no --allow is search-only, and refuses every exec.
• --status — report a live session and its remaining time without extending it.

On success it prints what it did and when the session ends:

Unlocked vault "acme" for 15m. The session ends 2026-08-28T09:15:00Z.
End it sooner with `custodian lock --vault acme`.
No --allow programs were declared, so this session is search-only: custodian exec is refused until you unlock with `--allow <absolute path>`.
The key's pages are locked into memory, so they will not be written to swap.

On a platform where Custodian cannot see the workstation lock, it adds that locking your screen will not end the session early — only its duration or custodian lock will.

The session cap

A session's duration is capped, and --for cannot raise the cap — a key resident for a working day is a key in a file with a nicer interface. The cap defaults to one hour and is only changed, deliberately, by the CUSTODIAN_MAX_SESSION environment variable. A --for above the cap is refused, naming both:

error: --for 4h is above the configured session cap of 1h. A longer session is a deliberate configuration change: raise CUSTODIAN_MAX_SESSION rather than passing a larger --for.

There is one session per vault: unlocking again while one is live reports the live one rather than starting a second.

custodian lock

Ends the live session and zeroes the master key from the broker's memory:

custodian lock --vault acme

Locked vault "acme"; the master key has been zeroed from the broker's memory.

custodian unlock --status

Reports a live session's remaining time and operation count, without extending it:

custodian unlock --vault acme --status

A session is live for vault "acme".
It ends 2026-08-28T09:15:00Z (in 12m 30s).