The data directory and the master key

Two things make a Studio installation, and you are responsible for keeping both.

On this page

Lose the master key, lose the stored secrets

Studio encrypts every secret with KERVAN_STUDIO_MASTER_KEY (AES-256-GCM). The key is never written to the database, and nothing can decrypt the secrets without it: not Studio, not the project, not a database backup. If the key is lost, the stored secrets must be deleted from the database and set again (below). Back up the key yourself, apart from the database, before you store the first secret.

What to keep

A Studio installation has two things to keep, and they belong in different places:

What	Where	Without it
The database	`studio.db` in the data directory	Servers, versions, users, keys and logs are gone.
The master key	`KERVAN_STUDIO_MASTER_KEY` (outside the data directory)	Stored secrets cannot be decrypted. Studio refuses to start until they are deleted from the database or the key is found.

Back up the master key once (a password manager or your secret store), and the database regularly. Keep them apart: someone who gets a database backup should not also get the key, and the database alone reveals no secret values.

The database is one SQLite file, studio.db, opened in WAL mode.
On Linux and macOS, the data directory is made 0700 and the files 0600. On Windows, keep the data directory somewhere only the Studio user can read.
Studio refuses to start when a migration fails, or when the database was written by a newer Studio.

Studio refuses to start without a master key, and refuses to start when a stored secret does not decrypt with the configured keys: it never runs with secrets it cannot use or protect. When the data directory already holds secrets and the key is missing, it says to set the original key, not to make a new one.

Losing the master key

Nothing can decrypt the stored secrets without their key, and Studio does not start while a stored secret fails to decrypt. To start over with a new key, stop Studio, back up the database, delete the secrets, start with the new key and set each secret again (each server’s Secrets tab lists the names its published versions use):

sqlite3 .kervan-studio/studio.db ".backup 'studio-before-new-key.db'"
sqlite3 .kervan-studio/studio.db "DELETE FROM secrets"

Servers, versions, keys and the audit log stay. Until a secret is set again, calls to a tool that uses it fail with “Secret NAME is not configured for host:port”.

Rotating the master key

Create a new key and give it the next version number: KERVAN_STUDIO_MASTER_KEY=2:<new base64>. A key without a version is version 1.
Move the old key to KERVAN_STUDIO_PREVIOUS_MASTER_KEYS=1:<old base64> (comma-separated if there are several).
Restart Studio. It re-encrypts every stored secret with the new key before it serves requests, and prints how many it re-encrypted.
Back up the database, then remove the old key from KERVAN_STUDIO_PREVIOUS_MASTER_KEYS.

If a secret cannot be decrypted with any configured key, Studio does not start and nothing is changed. Database backups made before the rotation still need the old key: keep it as long as you keep those backups.

Backups

Backing up and restoring the database, and upgrading Studio, are on backup, restore and upgrades.