Recover Locked Out Scryer

If Scryer has form login enabled but no local full-admin user has a usable password, start it once with:

SCRYER_RECOVERY_ADMIN_PASSWORD

On that boot, Scryer temporarily enters instance recovery mode.

This recovery path requires Scryer 0.16.1 or newer.

What Recovery Mode Does

When SCRYER_RECOVERY_ADMIN_PASSWORD is set and non-empty, Scryer:

• Creates or repairs the reserved local account recovery-admin
• Sets that account’s password to the value from SCRYER_RECOVERY_ADMIN_PASSWORD
• Grants recovery-admin full app permissions and full library grants
• Clears TOTP enrollment, TOTP recovery codes, passkeys, and failed login attempts for recovery-admin
• Disables MFA step-up requirements for the instance
• Forces form login off for that boot

That last point matters: authentication is disabled for the recovery boot. Before using recovery mode, block all external access to Scryer. Stop any reverse proxy exposure, close router or firewall forwards, disable public ingress, and make sure only a trusted local machine or trusted local network can reach the instance. Remove the environment variable immediately after you regain control, and restart Scryer normally.

When To Use This

Use recovery mode when:

• All local full-admin accounts are locked out
• The only admin account belonged to an external identity provider and local login is no longer usable
• You need to bypass MFA or passkey state so you can repair real admin access
• Scryer tells you: start with SCRYER_RECOVERY_ADMIN_PASSWORD set to recover the instance

Do not leave this environment variable configured permanently.

Recovery Flow

1. Block all external access to Scryer so the recovery boot is reachable only from a trusted local machine or trusted local network.
2. Stop the existing Scryer process or service.
3. Start Scryer once with SCRYER_RECOVERY_ADMIN_PASSWORD set to a strong temporary password.
4. Open the instance locally and repair access:
   • create or repair your real admin account
   • reset passwords as needed
   • review MFA and passkey settings
5. Remove SCRYER_RECOVERY_ADMIN_PASSWORD.
6. Restart Scryer normally.
7. Re-enable external access only after normal sign-in works again.
8. Sign in with the repaired account or with recovery-admin if you intentionally kept it for follow-up cleanup.

Homebrew Example

Homebrew installs Scryer as a managed macOS service and reads environment overrides from:

$(brew --prefix)/etc/scryer/config.env

Open that file:

nano "$(brew --prefix)/etc/scryer/config.env"

Add a temporary line like this:

SCRYER_RECOVERY_ADMIN_PASSWORD=choose-a-strong-temporary-password

Restart the service:

brew services restart scryer

After you regain control, remove the line from config.env and restart again:

brew services restart scryer

Docker Compose Example

Add the recovery password as a temporary environment variable in your docker-compose.yml:

services:
  scryer:
    image: ghcr.io/scryer-media/scryer:latest
    environment:
      SCRYER_RECOVERY_ADMIN_PASSWORD: "choose-a-strong-temporary-password"

Restart the container:

docker compose up -d

After you regain control, remove the environment variable from the compose file and redeploy:

docker compose up -d

Binary Example

For a direct binary install on Linux or macOS, start Scryer once with the environment variable in front of the command:

SCRYER_RECOVERY_ADMIN_PASSWORD='choose-a-strong-temporary-password' ./scryer

On Windows PowerShell, use:

$env:SCRYER_RECOVERY_ADMIN_PASSWORD = "choose-a-strong-temporary-password"
.\scryer.exe

Then stop Scryer and start it again without the variable.

What To Do After Recovery

Before you consider the instance fixed:

• set a permanent password on the admin account you actually want to keep using
• confirm at least one local full-admin account has a usable password
• review Settings → Security if form login or MFA policy needs repair
• review Settings → Users and remove or downgrade recovery access if appropriate
• restart once without SCRYER_RECOVERY_ADMIN_PASSWORD and verify normal sign-in works again

Important Notes

• recovery-admin is a reserved username for instance recovery.
• An empty SCRYER_RECOVERY_ADMIN_PASSWORD value is invalid.
• Recovery mode is meant to be temporary, not a permanent auth configuration.
• Because form login is forced off for the recovery boot, treat that run as a maintenance window.

Related Concepts

• Security — form login, MFA policy, and related auth controls
• Users — restore a durable full-admin login after recovery
• Homebrew — where the Homebrew service reads environment overrides
• Docker — container deployment layout used in the Docker example
• Binary — direct executable deployment model used in the binary example