Reset administrator access

Recover local administrator access with the CLI or a one-time Docker environment variable.

Use these recovery methods when you cannot sign in as the administrator.

Reset the password with the CLI

Use the local CLI when you can access the host or container.

From the Docker host, run:

docker exec -it crosswatch cw --local auth setup --username admin --no-token

From inside the CrossWatch container, run:

cw --local auth setup --username admin --no-token

CrossWatch prompts for a new password and confirmation.

This method:

• Replaces the administrator password.
• Clears active web sessions.
• Preserves all other CrossWatch configuration and data.

Use this method when only the password needs replacement.

Reset authentication with an environment variable

For Docker or Unraid installations, set the one-time recovery variable (see below, pick one)

environment:
  CW_RESET_AUTH_ONCE: "true"

environment:
    CW_RESET_AUTH_ONCE=1

Restart the CrossWatch container.

During startup, the application resets administrator authentication. The log includes:

[BOOT] CW_RESET_AUTH_ONCE detected: app authentication was reset.
Remove the env var and set a new username/password in the UI.

Then:

1. Open the CrossWatch web interface.
2. Configure a new administrator username and password.
3. Remove CW_RESET_AUTH_ONCE from Docker or Unraid.
4. Restart CrossWatch again.

Remove CW_RESET_AUTH_ONCE after recovery. Otherwise, a later restart resets authentication again.

This method resets:

• Administrator username and password.
• Active sessions and API tokens.
• Last login state.

It does not perform a factory reset. Providers, sync pairs, profiles, databases, and other configuration remain intact.

Choose a method

Use the CLI when you forgot the password and have shell access.

Use CW_RESET_AUTH_ONCE to reset the full administrator authentication state. Then configure credentials through the web interface.