Install and the first admin

Studio runs from a clone of the repository. Until the first admin exists, it listens on 127.0.0.1 only.

Requirements

• Node.js 22.23.3 or a later 22.x, or 24.21.0 or later. Studio refuses anything else with one line, before it loads.
• pnpm (through corepack enable), Git, and a place for the data directory that only the Studio user can read.

Build and start

git clone https://github.com/aligoren/getkervan.git kervan
cd kervan
corepack enable
pnpm install
pnpm build

Create a master key once, and keep it somewhere safe outside the data directory (a password manager, a secret store). Read the data directory and the master key first: without the key, stored secrets cannot be recovered.

This writes a new key into .env.studio without showing it, and refuses to overwrite an existing file. Copy the key from the file to your password manager:

node -e "require('fs').writeFileSync('.env.studio', 'KERVAN_STUDIO_MASTER_KEY=' + require('crypto').randomBytes(32).toString('base64') + '\n', { mode: 0o600, flag: 'wx' })"

Then start Studio with it. Node reads the file (--env-file), so the key is never on the command line or in your shell history:

node --env-file=.env.studio apps/studio/bin/kervan-studio.js start

Both commands are the same in PowerShell and cmd. The repository’s .gitignore keeps .env.* files out of Git. On Windows the file mode does not apply: keep the folder private.

The database goes into .kervan-studio/ in the current folder (KERVAN_STUDIO_DATA_DIR changes it). A folder Studio creates gets a .gitignore that keeps it out of Git, and Studio warns at start when Git could still commit the database.

The first admin, in the browser

On the first start, Studio listens on 127.0.0.1 only, whatever KERVAN_STUDIO_HOST says, and prints a one-time setup token, valid for 30 minutes (a restart prints a new one and invalidates the old one). Open http://127.0.0.1:4310/setup, paste the token, and choose the admin’s email and password (at least 12 characters).

Once the admin exists, Studio also listens on KERVAN_STUDIO_HOST.

The first admin, from the shell

Where the browser cannot reach Studio’s loopback address (a container, a remote server without a tunnel), create the first admin with a command on the host instead:

node --env-file=.env.studio apps/studio/bin/kervan-studio.js create-admin --email admin@example.com

• It asks for the password twice and does not show it (type it after the prompt appears: what is typed before that, the terminal itself shows, as with any password prompt). Without a terminal, pipe it in with --password-stdin (one line). The password is never taken from an argument or an environment variable: those end up in shell history and process listings.
• The email and the password get the same checks as the setup page.
• It needs the same KERVAN_STUDIO_DATA_DIR and KERVAN_STUDIO_MASTER_KEY as start (a missing or wrong key is reported the same way), and works whether or not Studio is running.
• It works only while there is no admin. Admins add other users in the UI; reset-admin (below) recovers an admin account.
• The setup token Studio printed stops working. A running Studio notices the new admin within a few seconds and starts listening on KERVAN_STUDIO_HOST; no restart is needed.
• It writes an audit event (studio.setup by the command line), without the password.
• The admin signs in with the password they chose (no forced change).

In a container (see docs/RELEASING.md for the image draft):

docker exec -it kervan-studio node apps/studio/bin/kervan-studio.js create-admin --email admin@example.com

Locked out

node apps/studio/bin/kervan-studio.js reset-admin [--email admin@example.com] [--password-stdin]

This command:

• sets a new password, generated and shown once, or read from stdin;
• ends that admin’s sessions;
• reactivates the admin if they were deactivated;
• writes an audit event (without the password).

It needs access to the data directory, so only someone with a shell on the host can run it.