# Modify and Reset Root Password

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

Source: https://doc.fastgpt.io/self-host/config/root-password
Last Updated: 2026-11-12

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:

```bash
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`:*

```bash
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:

```bash
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`:

```bash
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:

```text
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:
   ```bash
   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.
