Account Recovery

A user has lost their authenticator app, their hardware key, or their phone — and they cannot log in. Because HitKeep stores all data locally and has no external identity provider, recovery is performed by an administrator with shell access to the server running HitKeep.

Caution

The recover command opens the DuckDB database directly and requires HitKeep to be stopped first. Running it against a live instance will fail — DuckDB only allows one writer at a time.

The --db flag defaults to hitkeep.db in the working directory. Pass it explicitly if your database lives elsewhere (e.g. /var/lib/hitkeep/data/hitkeep.db).

Recovery Steps

systemd

sudo systemctl stop hitkeep

Then run the recovery command and restart:

hitkeep recover disable-2fa \
  --email locked-user@example.com \
  --db /var/lib/hitkeep/data/hitkeep.db

sudo systemctl start hitkeep

Docker

Stop the running container, then spin up a temporary container with the same image and data volume to run the recovery command, then restart normally:

# 1. Stop the running container
docker stop hitkeep

# 2. Run recovery in a temporary container against the same volume
docker run --rm \
  -v hitkeep-data:/var/lib/hitkeep/data \
  ghcr.io/pascalebeier/hitkeep:latest \
  recover disable-2fa \
    --email locked-user@example.com \
    --db /var/lib/hitkeep/data/hitkeep.db

# 3. Start the container again
docker start hitkeep

With Docker Compose:

docker compose stop hitkeep

docker compose run --rm hitkeep \
  recover disable-2fa \
    --email locked-user@example.com \
    --db /var/lib/hitkeep/data/hitkeep.db

docker compose start hitkeep

Manual process

pkill hitkeep

hitkeep recover disable-2fa \
  --email locked-user@example.com \
  --db /path/to/hitkeep.db

hitkeep -db /path/to/hitkeep.db

After Recovery

Advise the user to:

1. Log in with their existing password.
2. Immediately re-enroll a second factor under Settings → Security.
3. If their password may also be compromised, change it under Settings → Security → Change Password.

Related

• Two-Factor Authentication
• Permissions & Roles
• Configuration Reference

Need a self-service account recovery flow with identity verification? HitKeep Cloud → includes automated, audited recovery workflows.