---
title: "Config, secrets and environment variables"
description: "Each config entry reaches every service of a stagelet as an environment variable. Stagely stores plain values, but for secrets only their names and keys."
url: https://stagely.dev/docs/setup/config
---

Each project has a config in the console, under **Config**. It holds two kinds of entries. Every service of every stagelet gets each entry as an environment variable. These variables override the values in your Compose files.

| Kind   | You add it in                                        | Its value lives in                            | Stagely sees the value? |
| ------ | ---------------------------------------------------- | --------------------------------------------- | ----------------------- |
| Value  | The console                                          | Stagely's config snapshots and deploy bundles | Yes                     |
| Secret | The console names it; the agent host holds the value | The agent's encrypted store                   | No                      |

## Plain values

Under **Values**, click **Add value**. Enter a name and a value, such as `GREETING` and `Hello`. Click **Save config**.

Compose files can use plain values in most fields, such as `image: postgres:${POSTGRES_VERSION}`. Some fields that the [Compose rules](https://stagely.dev/docs/app/compose.md) check refuse variables.

Limits: a name is an environment variable name of at most 128 characters. A value is at most 32 KiB. The names and values of all plain values together are at most 256 KiB. A config holds at most 200 entries.

## Secrets

A secret has two halves. In the console, you add the reference: the environment variable name and the key of the secret in the agent's store. On the agent host, you store the value under that key.

### Add the reference

Under **Secrets**, click **Add secret**. Enter the variable name, such as `DATABASE_PASSWORD`, and the agent secret key, such as `db_password`. Click **Save config**.

### Store the value on the agent host

Connect to the agent host with the SSH key that setup created. Then store the value as the agent's user. `read -s` keeps the value off the screen and out of the shell history.

```sh
ssh -i ~/.stagely/cli/setup/production/operator_ed25519 \
  root@<agent host address>
read -rs value
printf %s "$value" |
  sudo -u stagely-agent stagely-agent secrets set \
    -data-dir /var/lib/stagely-agent db_password
```

List and delete secrets the same way:

```sh
sudo -u stagely-agent stagely-agent secrets list \
  -data-dir /var/lib/stagely-agent
sudo -u stagely-agent stagely-agent secrets delete \
  -data-dir /var/lib/stagely-agent db_password
```

Keys are 1 to 128 letters, digits, dots, dashes or underscores.

The store is `secrets.json` in the agent's data directory. The agent encrypts it with AES-256-GCM, under the key in `secrets.key` in the same directory. When you move the agent, keep both files. Without the key file, nobody can read the store. The encryption protects the store file when it leaks alone, such as in a backup of that one file. It does not protect against someone who can read the whole data directory.

The agent can also read secret values from a dotenv file that your pipeline writes. Give the agent the file with its `-secrets-file` flag. When the store and the file hold the same key, the file wins.

## How secrets reach your app

- A secret reaches containers only as an environment variable. Compose files cannot use secrets as variables.
- The agent writes the values to the stagelet's machine in a file that only root can read. The values never enter the deploy bundle that Stagely keeps.
- Before a log line leaves the agent, the agent replaces each secret value in it with `[secret]`. The agent does this line by line, so it hides a value with line breaks one line at a time. It does not hide a value, or a line of a value, that is shorter than 4 characters.
- When a deploy names a secret that the agent does not have, the deploy fails at the **Secrets** step, before any machine starts. The error names the missing key.

## When config changes

Each deploy freezes the config as it was when Stagely queued the deploy. After you change the config, deploy again: push a commit, comment the deploy command, or click **Deploy** in the console. A reset reapplies the last good deploy's config, with the agent's current secret values.

If two people edit the config at the same time, the second save fails. This keeps the first person's change. Reload the page, then save again.