Docs › Recovery

🔑 Recovery guide

If something's gone wrong on your Sovereign self-host install — typically a forgotten dashboard password — this guide gets you back in. Three scenarios in priority order, easiest first. None require Scarif's involvement; everything happens on YOUR install.

Scenario 1 — I forgot my dashboard password

You're a few seconds away from being back in if you saved the recovery code from setup. The recovery code is a long single-use code shown on the green “🔑 Save your recovery code” screen at the end of the setup wizard, with the prompt to save it next to your Scarif licence file.

It looks like:

SCARIF-RECOVER-eyJrIjoidGVuYW50LWFkbWluIiwidCI6...

How to use it

  1. Open your install URL in a browser (e.g. https://your-scarif-install.example.com).
  2. Visit /operator/reset.
  3. Paste the SCARIF-RECOVER-... code.
  4. Type a new password twice (minimum 8 characters).
  5. Click Set new password.
  6. Auto-redirected to /login — sign in with your username and the new password.

Successful redemption deletes the code (single-use). If you want a fresh one, re-run setup at /setup from the address bar — the wizard pre-fills, you confirm your existing config, and a new recovery code is minted at the end.

Scenario 2 — I lost the recovery code too

You still have one path that doesn't lose any data: mint a one-time CLI reset token. Requires shell access to your install host (whatever runs your Docker container).

Step 1 — find your username

docker compose exec scarif-one node /app/scripts/operator-reset.mjs --list

Output looks like:

Tenant admins (dashboard logins — most customers use these):
  --tenant <slug>   --username <name>   role: admin   ...

The <slug>is your workspace's internal identifier. The <name> is what you type in the Usernamefield at login.

Step 2 — mint a reset token

docker compose exec scarif-one node /app/scripts/operator-reset.mjs \
  --tenant <slug> --username <name>

Output prints a 64-character hex token and an expiry timestamp (30 minutes from minting).

Step 3 — redeem it

  1. Visit /operator/reset on your install.
  2. Paste the 64-char hex token in the Recovery code or CLI reset token field.
  3. Type a new password twice.
  4. Submit. Sign in at /login.

Single-use: successful redemption deletes the token file on disk.

Scenario 3 — I lost everything (recovery code AND shell access)

This is operator-of-last-resort territory. To recover you'll need physical or root access to your install's data volume.

The fix is to delete the tenant's auth file. This loses your dashboard credentials and only your dashboard credentials — your licence, brand profile, AI keys, integrations, and all generated content stay intact.

# Find the data volume's mount point on the host
docker compose exec scarif-one ls /data/tenants

# Delete the auth file for your tenant
rm /data/tenants/<slug>/auth.json

# Restart the container so the change takes effect
docker compose restart scarif-one

On the next visit to the install URL, the root redirect will send you to /setup. The wizard pre-fills everything except the admin credentials. Walk through to Step 6, set a fresh username + password, hit Activate. You'll get a new recovery code at the end — save it this time.

Edge cases

I forgot which Scarif install I'm even on

Open your install URL in a browser and read the page header — your business name + workspace slug are shown top-left of the dashboard. Or visit /api/healthfor a non-auth page that prints the install's machine metadata.

If you don't even remember your install URL, the email you got at purchase has it in the install instructions. Search your inbox for “Scarif” + “licence”.

I lost my licence file entirely

Email [email protected] from the address that bought the licence. We re-issue at no cost — the registry keeps a record of every Sovereign licence we've ever shipped. You'll get a fresh SCARIF-... code by email within ~1 business day.

Something else broke and the dashboard won't load

  1. docker compose logs scarif-one --tail 200 — look for [scheduler], [auth], or [install/] warnings near the start of the output. These are the most diagnostic prefixes.
  2. curl -i http://localhost:3000/api/health — if this returns 200 with JSON, the server is alive. If it returns 503, the response body tells you which check is failing.
  3. Reach out: [email protected] — include the last 100 lines of logs plus the /api/health output. We respond within 1 business day.

What this guide doesn't cover