The master key & encryption at rest

Everything sensitive Hezo holds - model API keys, OAuth tokens, signing keys, and other secrets - is encrypted at rest. The key that protects it all is the master key, and only you hold it.

A twelve-word key only you hold

On first run, Hezo generates a twelve-word master key and shows it to you once. From it, Hezo derives the key used to encrypt and decrypt your vault using strong, authenticated encryption (AES-256-GCM).

• It is held in memory only while Hezo is running - never written to disk.
• After a reboot, crash, or direct service restart, the master key has to be provided again. This is deliberate: nobody who gets a copy of your data directory can read your secrets without the phrase.

Treat it like the seed phrase of a crypto wallet: write it down and keep it somewhere both safe and hard to lose.

Locked and unlocked

Hezo has a simple gate around your secrets:

• Unset - first run, before you've created a master key.
• Locked - Hezo is running but the master key hasn't been provided yet. Secrets can't be read and agents can't run. This is the default state for a new process.
• Unlocked - you've provided the correct phrase; Hezo can decrypt secrets and agents run normally.

You unlock from the web app's gate screen. Self-hosting, you can also unlock a single startup non-interactively by passing the --master-key flag / HEZO_MASTER_KEY environment variable to that one invocation (see Self-hosting on a VPS) - but don't persist the phrase to disk to do it (see Keep it off the server below).

On Hezo Cloud the gate screen is the only way in: your own browser generates the phrase and it never reaches us, so we hold no copy and cannot recover it for you. See Data & security on Hezo Cloud.

Keep it off the server

The master key lives in memory only and is never written to disk, which is what makes the encrypted data directory useless to anyone who copies it without the phrase. Don't undo that by storing the key on the server yourself - not in the config file (/etc/hezo/hezo.config.cjs), an env file, the systemd unit, a shell profile, a same-host secrets file, or a note in the repo. Hezo refuses a masterKey key in the config file for exactly this reason. Note that Bun also auto-loads a .env from the working directory, so a HEZO_MASTER_KEY line there is picked up like any other, and the same rule applies. A copy of the phrase sitting next to the encrypted vault means a stolen disk image, a leaked backup, or anyone who can read the box can decrypt everything - exactly what encryption at rest is meant to prevent.

Starting locked by default is deliberate. Two startup paths can supply the key in memory: an in-app update hands it from the surviving supervisor to the new process, and --master-key / HEZO_MASTER_KEY supplies it to one invocation. Neither path writes it to disk. A reboot, crash, or direct service restart has no surviving handoff and comes up locked unless you deliberately provide the one-shot input. Keep the only durable copy somewhere safe off the server. See Updating.

Your password vs. the master key

The master key and your password do two different jobs:

• The master key unlocks the instance - it turns encryption on and, once entered (or supplied via HEZO_MASTER_KEY), it's done for that run. It is not how you sign in.
• Your admin password is how you sign in to the web app. On first run, right after the master key, you set a password; from then on each browser session is authenticated with it. Your password (like the master key) never leaves your browser - Hezo stores only a verifier it can check a login against, never the password itself.

This split is what lets you run Hezo on a public network safely: access is gated by the admin password on every request, while the master key stays purely about unlocking encryption. A reboot, crash, or direct service restart comes up locked unless that invocation deliberately receives the one-shot --master-key or HEZO_MASTER_KEY input. You can otherwise unlock from the browser gate. Everyone still has to sign in with the password to reach the app. See Secure remote access.

Changing your password? While signed in, go to Settings → Users & access, enter your current password and the new one twice, and save. Your session stays signed in.

Forgot your password? Reset it with your master key: on the sign-in screen choose Forgot password? Use your master key, enter the twelve words, and set a new one. The master key outranks the password, so it is also your password-recovery path.

Upgrading an existing instance? Your admin account is given the default password password so you can sign in right away - change it immediately in Settings → Users & access, especially before exposing the instance to a network.

What's encrypted

The master key protects all confidential data at rest, including:

• AI provider API keys and subscription tokens,
• OAuth tokens for connected accounts and SaaS integrations, and
• the per-project SSH/signing keys used for git (see Container isolation).

Recovery

A forgotten password is easy to recover - reset it with your master key (above). A password you still know can be changed any time in Settings → Users & access.

A lost master key is different: there is intentionally no backdoor. If you lose it, the encrypted data can't be recovered - your only path forward is to reset the instance and start over (hezo --reset, see Backup & recovery). Keep the phrase somewhere you trust.