FastGPTFastGPT

Modify and Reset Root Password

Guide on initial activation, regular updates, and CLI password resets for the self-hosted FastGPT root administrator account

The default administrator username in FastGPT is root. Starting from version v4.17.3, FastGPT introduces an account activation mechanism and a built-in password reset command-line tool. It removes the legacy behavior of overwriting the administrator password on every container restart via the DEFAULT_ROOT_PSW environment variable (any residual DEFAULT_ROOT_PSW in v4.17.3+ Compose templates is ignored at runtime), improving the security of administrator accounts.

This guide explains how to change or reset the root password across different scenarios.


Scenario 1: Initial Deployment Login and Activation

In version v4.17.3 and later, newly created FastGPT instances have a fixed default initial password of 123456, and the account is initially set to inactive. For instances upgraded from an earlier version, a root account without a status field is also set to inactive at startup, so the activation modal appears on first login as well; sign in with the existing password in that case.

  1. Open the FastGPT web access address in your browser.
  2. Sign in with the administrator credentials:
    • Username: root
    • Initial Password: 123456
  3. After logging in, a non-dismissible Account activation dialog will appear, requiring you to set a new password.
  4. Enter and confirm your new password (at least 8 characters, containing at least two of uppercase letters, lowercase letters, digits, and special characters), then click Confirm to complete activation. Keep your new password in a safe place.
🤖

To protect system security, you must complete the activation and set a new password on your first login before you can use system features.


Scenario 2: Regular Password Updates in the Web UI

If you know the current password and are currently logged in, you can update your password directly through the web interface:

  1. Sign in to the FastGPT platform as root.
  2. Click Account in the left navigation to open Personal information.
  3. Under General information, click Change on the Password row to open the modal dialog.
  4. Complete identity verification with your current password, enter a new password meeting the complexity rules (at least 8 characters with at least two of uppercase, lowercase, digits, and special characters), and click Confirm.
  5. The new password takes effect immediately.

Scenario 3: Resetting Password via CLI When Forgotten

If you forget the root password and cannot log into the web interface, you can run the built-in password reset script directly inside the FastGPT application container.

This script connects directly to MongoDB to update the password digest. It does not require restarting the service container and will not interrupt running tasks.

1. Docker Compose Deployments

Navigate to the deployment directory containing docker-compose.yml on your server and run:

docker compose exec fastgpt-app node /app/scripts/reset-root-password.cjs 'your_new_password'

If you are using an older Docker Compose version (standalone binary), replace docker compose with docker-compose:

docker-compose exec fastgpt-app node /app/scripts/reset-root-password.cjs 'your_new_password'

2. Standalone Docker Container

If running FastGPT with docker run, execute the command using the container name or ID:

docker exec -it <container_name_or_id> node /app/scripts/reset-root-password.cjs 'your_new_password'

3. Kubernetes / Helm Deployments

In a Kubernetes cluster, run the command inside the FastGPT Pod using kubectl exec:

kubectl exec -it <fastgpt-pod-name> -n <namespace> -- node /app/scripts/reset-root-password.cjs 'your_new_password'

Verification

When the operation succeeds, the terminal outputs:

root 密码已重置

After the reset, you can sign in to the web interface with the new password. The CLI script only updates the password in the database and does not clear existing sessions, so signed-in sessions remain valid; to sign out other sessions, change the password once in the web interface.

The CLI script only checks that the password is nonempty; choose a strong password that satisfies the web complexity rules (at least 8 characters with at least two of uppercase, lowercase, digits, and special characters).

🤖

If your new password contains special characters (such as $!#), wrap the password argument in single quotes ' ' on the command line to prevent your host shell from interpreting or expanding them.


Scenario 4: Legacy Versions (v4.17.2 and Earlier)

For version v4.17.2 and earlier, the built-in CLI script is not available, and the root password is controlled by environment variables:

  1. Open docker-compose.yml in your deployment directory.
  2. Locate the DEFAULT_ROOT_PSW environment variable (or the x-default-root-psw YAML anchor) and update its value to your desired password.
  3. Restart the FastGPT service to apply the change:
    docker compose down
    docker compose up -d
  4. During container startup, the database root password will be automatically updated to the value specified in the environment variable.
Edit on GitHub

Last updated