Reset an Admin Password

Locked out of your self-hosted instance? GridNMS ships a recovery script that resets an admin account directly in the database — for a forgotten password, an email that never saved, or an MFA / passkey lockout. It talks straight to the database using the same credentials the server uses, so it works even when you can’t sign in.

Self-hosted only

This is for self-hosted instances, where you have shell access to the server. On GridNMS Cloud (SaaS), use the password-reset link on the login screen, or contact support@gridnms.io.

Run it

Run the script inside the tenant-server container:

docker compose -f docker-compose.selfhosted.yml exec tenant-server \
  npx tsx src/scripts/reset-admin-password.ts

With no arguments it targets your admin account, generates a strong password, and prints it along with the username to log in as. Example output:

✓ t_xxxxxxxx: reset id=1 name="admin" — log in as "admin@example.com"

Reset 1 account(s). New password:

  gn-Xk9c2Qv3mfPa

Log in with the username/email shown above (usernames are case-insensitive).

Caution

The new password is printed to your terminal. Copy it, sign in, then change it from Profile and clear your shell history if the terminal is shared.

Options

Option	What it does
<newPassword> (positional) or --password <pw>	Set a specific new password. Omit either and a strong one is generated and printed.
--user <name or email>	Target a specific account by username or email. Default: the admin-group account with the lowest id.
--email <email>	Also set the account’s email — handy if it never saved during setup.
--clear-mfa	Also turn off TOTP and passkey on the account — use this for a full MFA/passkey lockout.
--clear-passkeys	Remove only the account’s passkeys, leaving an authenticator app (TOTP) in place — use this when you’ve lost a passkey but can still enter a TOTP code.
--tenant <schema>	Restrict to one tenant (a self-hosted instance has exactly one, so you rarely need this).

Common scenarios

Forgot the password — let it generate one:

docker compose -f docker-compose.selfhosted.yml exec tenant-server \
  npx tsx src/scripts/reset-admin-password.ts

Set a password you choose:

docker compose -f docker-compose.selfhosted.yml exec tenant-server \
  npx tsx src/scripts/reset-admin-password.ts 'NewPass123!'

Locked out by MFA or a lost passkey, with no other way in — reset the password and clear everything:

docker compose -f docker-compose.selfhosted.yml exec tenant-server \
  npx tsx src/scripts/reset-admin-password.ts --clear-mfa

Lost your passkey but still have your authenticator app — clear only the passkey, keep TOTP:

docker compose -f docker-compose.selfhosted.yml exec tenant-server \
  npx tsx src/scripts/reset-admin-password.ts --user admin --clear-passkeys

The admin email never saved — set it while resetting:

docker compose -f docker-compose.selfhosted.yml exec tenant-server \
  npx tsx src/scripts/reset-admin-password.ts --email you@example.com --clear-mfa

A specific (non-default) admin account:

docker compose -f docker-compose.selfhosted.yml exec tenant-server \
  npx tsx src/scripts/reset-admin-password.ts --user jsmith 'NewPass123!'

After resetting

1. Sign in with the username or email the script printed (usernames are case-insensitive) and the new password.
2. Change the password from Profile.
3. If you cleared MFA, re-enroll your passkey or authenticator from Profile.

Notes & safety

• The script reads the database connection from the server’s environment (GRIDNMS_DB*), so it needs no running login session — but it does require shell access to the host running the stack. Treat that access as admin-level.
• It only updates the password (and, if asked, the email / MFA flags) — it never changes roles or permissions.
• Still stuck after a reset? Check that you’re logging in at the same URL set as your access URL during setup, and see Troubleshooting.