Create new superadmin

Questions
2

Here is the recovery procedure for a server that has lost all superadmin access:

Regain access using the Recovery Administrator

The built-in mechanism for this exact situation is the STALWART_RECOVERY_ADMIN environment variable. It creates a temporary bypass credential that works even when the directory has no admin accounts left.

Step 1 - Set the environment variable before starting (or restarting) Stalwart:

STALWART_RECOVERY_ADMIN=admin:yourchosenpasword

This account bypasses the directory entirely, so it works regardless of what is in the database.

Step 2 - Log in with those credentials via the WebUI or CLI and either:

  • Promote an existing user account to administrator by assigning it the appropriate admin Role and permissions, or
  • Create a brand-new account and assign it admin permissions.

Step 3 - Remove the variable once you are done. The docs are explicit about this:

STALWART_RECOVERY_ADMIN must not be left permanently set on a production deployment. It is a backdoor credential intended to rescue a server that has lost normal access, not a primary login.

Restart the server without the variable set to return to normal operation.

Note: If you also need to stop mail processing during the recovery work, you can combine this with STALWART_RECOVERY_MODE=1, which disables all background services and only exposes the management HTTP endpoint on port 8080.

Relevant docs:

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong.