# Environment Variables

Declare the environment variables your automations need under the top-level `app.env[]` array. Each entry documents a variable, whether it's required, and an optional default. At runtime, reference a value anywhere a template or connection prop is accepted with `$env.VAR_NAME`.

```yaml
env:
  - { key: SLACK_WEBHOOK_URL, description: Slack incoming webhook URL }
  - { key: STRIPE_SECRET, description: Stripe API secret, required: true }
  - { key: REGION, description: Default region, required: false, default: eu-west }
```

## Env Var Properties

| Property      | Description                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | Variable name in uppercase snake*case (`^[A-Z]A-Z0-9*]\*$`, e.g. `API_KEY`). **Required.**                                        |
| `description` | What the variable is used for.                                                                                                    |
| `required`    | Whether the variable must be set (default `true`). When required and unset, validation fails at boot.                             |
| `default`     | Fallback value used when the variable is not set. When both `required` and `default` are present, `default` acts as the fallback. |

Keys must be unique across the app.

## Referencing Secrets

Use `$env.VAR_NAME` in action props, connection props, and webhook auth:

```yaml
connections:
  - name: openai-key
    type: bearer
    props: { token: $env.OPENAI_API_KEY }

automations:
  - name: notify
    trigger: { type: record, table: orders, events: [create] }
    actions:
      - name: ping
        type: http
        operator: post
        props:
          url: $env.SLACK_WEBHOOK_URL
          body: { text: 'New order {{trigger.data.id}}' }
```

:::callout
**Secrets are never logged.** Values resolved from `$env` are redacted from run logs, step outputs shown in the admin UI, and the runs API. Store credentials in `$env` (or a connection) rather than inlining them in action props.
:::

## Frugal-by-Default Operator Env

Beyond `app.env` (which the schema author declares), Sovrium's runtime footprint is governed by operator-controlled `ECO_*` environment variables (e.g. `ECO_IMAGE_FORMAT`, `ECO_AI_PROVIDER_PRECEDENCE`). These are **not** part of the app schema — operators opt out, never in. AI actions and image transforms invoked from automations honor these defaults automatically. See [AI Overview](/en/docs/ai-overview) and [Image Transforms](/en/docs/image-transforms).

## Related Pages

- [Connections](/en/docs/automation-connections) — credential blocks that consume `$env`.
- [Actions Overview](/en/docs/automation-actions-overview) — where `$env` is interpolated.
- [HTTP & Webhooks](/en/docs/automation-http-actions) — secrets in request headers.