Environment variables & secrets

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.

Create the environment variable

Open Settings > Variables & Secrets 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.

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.

Add the references to the template

Open Files, select the serverhost, and edit the plugin configuration in the matching template. For example, place this file at templates/lobby/plugins/DatabasePlugin/config.yml:

templates/lobby/plugins/DatabasePlugin/config.yml

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.

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.

Use references in configurators and workflows

Both reference types also work as Configurator values. Add this entry under paths in your custom configurator to manage the same database settings:

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, 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.

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.

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

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.

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.

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.

Introduction

Setup

Configuration

Plugins

Environment variables & secrets

Choose an environment variable or a secret

Use both in a plugin configuration

Use references in configurators and workflows

Change or delete a value

How values are stored and used

Keys and values

Troubleshooting

​Choose an environment variable or a secret

​Use both in a plugin configuration

​Use references in configurators and workflows

​Change or delete a value

​How values are stored and used

​Keys and values

​Troubleshooting

Choose an environment variable or a secret

Use both in a plugin configuration

Use references in configurators and workflows

Change or delete a value

How values are stored and used

Keys and values

Troubleshooting