> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables & secrets

> Reuse network configuration values and credentials in templates, configurators, and workflows

## Choose an environment variable or a secret

Environment variables and secrets store named values for your network. Reference them in templates, configurators, or workflows so you can change a value without editing every file that uses it.

|                   | Environment variable                                 | Secret                                                                       |
| ----------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------- |
| Use for           | Shared settings, such as a database hostname         | Passwords, tokens, and other credentials                                     |
| Reference         | `{{ env.DATABASE_HOST }}`                            | `{{ secrets.DATABASE_PASSWORD }}`                                            |
| Read after saving | Members with access can reveal and edit the value    | The dashboard cannot show the saved value; replace it by rotating the secret |
| Storage           | The controller encrypts the value and can decrypt it | Your browser encrypts the value; only your serverhosts can decrypt it        |

Both are available to every serverhost in the network. Use separate networks if values must not be shared between hosts.

## Use both in a plugin configuration

This example stores a database hostname as an environment variable and its password as a secret. You need a connected serverhost, a database account, and a plugin that uses that database.

<Steps>
  <Step title="Create the environment variable">
    Open **[Settings > Variables & Secrets](https://dash.simplecloud.app/redirect?target=%2Fsettings%2Fsecrets)** in the dashboard. Under **Network variables**, select **Add variable**.

    Enter `DATABASE_HOST` as the key and your database hostname as the value, such as `db.internal.example`. Select **Add variable** to save it. You can reveal the saved value with the eye icon.
  </Step>

  <Step title="Create the secret">
    Under **Network secrets**, select **Add secret**. Enter `DATABASE_PASSWORD` as the key and your database password as the value, then select **Encrypt & save**.

    A serverhost must register the network's encryption key before you can add secrets. If the dashboard asks for a serverhost, start or reconnect one. After saving, you can see the secret's key but cannot reveal its value.
  </Step>

  <Step title="Add the references to the template">
    Open **Files**, select the serverhost, and edit the plugin configuration in the matching [template](/docs/en/manual/setup/templates). For example, place this file at `templates/lobby/plugins/DatabasePlugin/config.yml`:

    ```yaml templates/lobby/plugins/DatabasePlugin/config.yml theme={null}
    database:
      host: "{{ env.DATABASE_HOST }}"
      port: 3306
      name: "minecraft"
      username: "simplecloud"
      password: "{{ secrets.DATABASE_PASSWORD }}"
    ```

    Adapt the path and database settings to your plugin and account. Keep the two references as shown. Use references in text configuration files, not in JAR files, worlds, databases, or archives.

    Make sure the template contains these references on every serverhost that can run your lobby servers.

    For a persistent server that already has this file, stop the server and edit its existing configuration from the server's **Files** page instead. A template does not replace an existing persistent-server file.
  </Step>

  <Step title="Start the server and check the connection">
    Start a new `lobby` server that uses this template. If you edited a persistent server, start it again.

    SimpleCloud inserts both values into the server's configuration before starting the process. The source template keeps its references.

    Confirm that the plugin connects to the database. The dashboard file editor still shows the references in the running file. Check the plugin's connection result to verify that it received the values.
  </Step>
</Steps>

## Use references in configurators and workflows

Both reference types also work as [Configurator](/docs/en/manual/configuration/configurators) values. Add this entry under `paths` in your custom configurator to manage the same database settings:

```yaml theme={null}
paths:
  - path: "plugins/DatabasePlugin/config.yml"
    type: "YML"
    data:
      database:
        host: "{{ env.DATABASE_HOST }}"
        port: 3306
        name: "minecraft"
        username: "simplecloud"
        password: "{{ secrets.DATABASE_PASSWORD }}"
```

Keep the other entries your configurator needs. Use environment and secret references in configuration values; they are not supported in the target `path`.

In [workflows](/docs/en/manual/configuration/workflows), use `{{ env.KEY }}` or `{{ secrets.KEY }}` in a step's `with` parameters. SimpleCloud resolves them when the workflow runs. Create the corresponding environment variable or secret before running it.

## Change or delete a value

Open the action menu next to the key under **Settings > Variables & Secrets**:

* For an environment variable, select **Edit variable**, change the value, and select **Save changes**.
* For a secret, select **Rotate secret**, enter the replacement value, and select **Rotate secret** to save it.

The key stays the same, so existing references keep working. Restart each affected server to apply the new value to its configuration. Running servers keep their previous values; rerun manual workflows that need the change.

Rotating `DATABASE_PASSWORD` changes only the value stored in SimpleCloud. Change the database account's password separately and keep the two values in sync. Servers using the old password may lose access until you restart them with the new value.

Before selecting **Delete variable** or **Delete secret**, remove its references. A server cannot start if one of its configuration files requires a missing value.

<Warning>
  SimpleCloud creates and manages `VELOCITY_SECRET` for secure proxy forwarding. Do not rotate or delete it manually. A changed forwarding secret must reach the proxy and every backend server together, or connections between them will fail.
</Warning>

## How values are stored and used

The controller stores both kinds of value encrypted. It can decrypt environment variables so members with access can read them in the dashboard.

Secrets are encrypted in your browser with the network's public key. The controller cannot decrypt them. Your serverhosts share the corresponding private key and decrypt secrets when a server or workflow needs them.

The running server receives the real values in its configuration files. Users and processes with direct access to the serverhost or server directory can read those files, including passwords. The dashboard editor and downloads show references in place of managed values.

### Keys and values

* Keys are case-sensitive and can contain up to 64 letters, digits, or underscores. Start with a letter or underscore. Secret keys can also contain hyphens.
* Environment variables and secrets have separate keys. `{{ env.HOST }}` and `{{ secrets.HOST }}` refer to different values, even when both keys are named `HOST`.
* Values can contain up to 16 KiB. Environment variables can be empty; secrets cannot. Both preserve whitespace and line breaks.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A reference is missing or the server cannot start">
    Check the serverhost log for the missing key. Open **Settings > Variables & Secrets** and confirm that the key exists in the correct section. Match its capitalization and use `env` for an environment variable or `secrets` for a secret.

    Create the missing value or correct the reference, then start the server again.
  </Accordion>

  <Accordion title="A changed value is not in use">
    Restart every server that uses the value and rerun any affected manual workflows. For a persistent server, check its existing configuration in **Files**. Editing the template does not replace that file.
  </Accordion>

  <Accordion title="The running file still shows a reference">
    The dashboard file editor and downloads replace managed values with their references before sending the file to your browser. Check the plugin's behavior or connection result to verify that it uses the value.
  </Accordion>
</AccordionGroup>