Emergency access

If sign-in is broken (a lost password, passkeys that cannot work without HTTPS, a lockout after failed attempts, a stale session), you do not need to reinstall. Every route below needs root on the host that runs the control plane, the same trust boundary as the data directory itself. None of them is reachable over the network, so none of them widens the attack surface.

Reset the admin password

sudo APP_DATA_DIR=/var/lib/levelrail-data /usr/local/bin/levelrail recover-admin --username admin

This sets a new random password and prints it once. It also ends that account's sessions and clears its login lockout. Use it when you can reach the sign-in page but cannot get past it.

Mint a short-lived root token

sudo APP_DATA_DIR=/var/lib/levelrail-data /usr/local/bin/levelrail emergency-token --ttl 1h

Prints a root API token once and never stores it in plaintext. Use it when the dashboard is unusable but you still need to fix something, for example enabling HTTPS or creating a user:

APP_API_URL=http://<server>:8080 APP_API_TOKEN=<token> levelrail-cli settings ingress get

What keeps it safe:

• Host access only. It opens the data directory directly, so it cannot be called over HTTP.
• Short lived. The default is one hour. --ttl accepts 1 minute up to 24 hours, and APP_EMERGENCY_TOKEN_MAX_TTL raises or lowers that cap on the control plane.
• Visible and revocable. It appears as emergency (host) under Settings, CLI Access with its expiry, and you can revoke it there before it runs out.
• Audited. Every mint is written to the audit log and the control plane log.
• Owned by an admin. It acts as the named admin (--username) or the first admin, never as an anonymous credential.

Make a break-glass token in advance

While you can still sign in, create a token in Settings, CLI Access named break-glass, with the abilities you would need and an expiry (30 days is a reasonable rotation). Store it in your password manager, outside the server. It works from anywhere and does not need host access, so treat it like a root password: scope it, expire it, and revoke it once used.

Other recovery routes

Situation	Route
First run, no admin yet	levelrail setup-token prints the one-time setup token
Bad upgrade	Restore the pre-migration snapshot with levelrail restore-db
CLI already logged in	levelrail-cli auth login --device, approved from any signed-in session

Passkeys and HTTPS

Passkeys only work on an HTTPS dashboard URL. On a fresh server without HTTPS, sign-in falls back to the password automatically. Enable HTTPS under Domains and passkeys become available.

See also

Learn about roles and access control in Access control.