# Environment variables

Literals, references, generated values, secrets and shared groups.

Each variable is one of:

| Form | Meaning |
| --- | --- |
| `KEY: text` | A literal. Numbers and booleans become strings. |
| `KEY: ${db.url}` | A reference. It can sit inside text: `"${cache.url}/1"`. `$$` is a literal `$`. |
| `KEY: { generate: secret }` | A random value made once per sandbox and kept for its life. `secret` is 48 URL-safe characters, `hex32` is 32 random bytes as 64 hex characters, `base64_32` is 32 random bytes as 44 base64 characters, `uuid` is a UUID. |
| `KEY: { generate: secret, length: 32 }` | Exactly that many characters (16 to 256): letters and digits for `secret`, lowercase hex for `hex`. Use it when the app wants a key of a given length, such as a 32-character encryption key. |
| `KEY: { secret: <ref> }` | A value from the project's secret store, in staging and production. Sandboxes never get staging or production values: it is empty there and `parity check` warns. Use `generate:` for values a sandbox needs. |
| `KEY: { unset: true }` | Remove a variable a group or the platform set. |

**References.** `${<name>.<attr>}` for a managed entry or a service, or the long forms `${managed.db.url}` and `${service.web.url}`. Services have `url` (`http://<service>:<port>`, inside the sandbox) and `public_url`, the URL of the first entry in `expose`; `public_url.<host>` is another exposed host's, as in `${web.public_url.link}`. Services reach public URLs too, so a server-side call to `${web.public_url}` (an OAuth callback, a webhook to itself) reaches the service. `${sandbox.id}` and `${sandbox.domain}` are also available: a public host is `<host>--${sandbox.domain}`. `${env_groups.<group>.<KEY>}` is a group's variable, generated values included, so one secret can have the name each image expects: `SPICEDB_GRPC_PRESHARED_KEY: ${env_groups.shared.AUTHZED_TOKEN}`. Kubernetes' `$(VAR)` form is refused, because it would reach the app as literal text. `KEY: db.url` without `${}` is refused, since it's almost always a forgotten `${}`. Inside a one-line `{ ... }`, quote references: `env: { A: "${db.url}" }`.

**Groups.** `env_groups.<name>` is a map of variables in the same forms. `env_from: [<name>]` gives them to a service. A value generated in a group is the same in every service that includes it, which is how services share a secret.

**Precedence.** Standard variables from `depends_on` first, then `env_from` groups, then the service's own `env`. Two groups setting the same key is an error.

**Reuse.** YAML anchors and aliases work anywhere, and `<<: *common` merges a mapping into another, as in Compose:

```yaml
x-deps: &deps [db, cache]
services:
  web:    { build: ., depends_on: *deps }
  worker: { build: { from: web }, command: npm run worker, depends_on: *deps }
```