# Environment variables and secrets

> How variables reach your services on Aria: wired from databases, generated, fixed, or typed by you. Commands for adding, importing and removing them.

Source: https://getaria.cloud/docs/environment-variables (updated 1 November 2026)

On Aria you declare every variable once, under `env` in `aria.yaml`, and say which services get it. Aria fills in the values it can work out itself, such as database addresses, and asks you only for secrets that nobody else can know. Secret values are entered by a person and are never shown to Aria AI or your coding agent.

## Where can a variable's value come from?

Each variable uses exactly one source.

| Source | Use it for | Example |
|---|---|---|
| `from` | An address or key Aria knows | `from: main.url` |
| `template` | A value built from addresses | `template: wss://${api.public_host}/live` |
| `generate` | A secret Aria creates once and keeps | `generate: secret` |
| `value` | A fixed setting that is not secret | `value: production` |
| none of these | A secret only you have | `required: true`, `secret: true` |

```yaml
env:
  DATABASE_URL:
    services: [api]
    from: main.url
  NODE_ENV:
    services: [api]
    value: production
  SESSION_SECRET:
    services: [api]
    generate: secret
  STRIPE_SECRET_KEY:
    services: [api]
    required: true
    secret: true
    description: Stripe secret key, from the Stripe dashboard
```

What `from` can read is listed in the [aria.yaml reference](https://getaria.cloud/docs/aria-yaml).

## Which services get a variable?

Only the ones in `services`. A variable with no `services` goes to every service, public website included, so always list `services` for a secret. A name that is not listed under `env` at all, for example one you pasted from a `.env` file, is saved but reaches no service until `aria.yaml` lists it.

## When does a variable have to be there at build time?

Browser bundles read variables while they are built. Names that start with `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`, `REACT_APP_`, `NUXT_PUBLIC_`, `EXPO_PUBLIC_` or `GATSBY_` are passed at build time automatically. Add `build: true` to any other variable your build reads. If the service has a Dockerfile, the Dockerfile must declare it with `ARG`.

Everything built into a browser bundle can be read by anyone who visits the site. Never put a database password, a service key or a generated secret into a variable with one of these prefixes.

## How do I see what is missing?

```bash
aria env ls
```

The table shows each variable's name, where its value comes from, whether it is set, and which services get it. It never shows values. A service with a missing required variable waits, and deploys on its own as soon as you add the value.

## How do I add a secret?

Run this in your own terminal and type the value. It is hidden as you type and goes straight to Aria, where it is stored encrypted.

```bash
aria env add STRIPE_SECRET_KEY
```

To give a value to one service only:

```bash
aria env add STRIPE_SECRET_KEY --service api
```

To pipe a value in on purpose, add `--stdin`. An agent cannot add a secret by accident, because a command that needs hidden input refuses to run without a person at the keyboard. You can also enter variables in the dashboard under Environment.

## How do I import a .env file?

```bash
aria env import .env
```

Aria shows names only: which it will set, which it sets itself (because `aria.yaml` wires them from a database or service), and which `aria.yaml` does not list. It then asks before saving. Add `--yes` to skip the question, and `--no-deploy` to save without redeploying. Values never appear in the output, so an agent can run this command, with your approval, without the values entering its conversation.

## How do I remove a variable?

```bash
aria env rm OLD_KEY
aria env rm OLD_KEY --service api
```

## How do I get the values on my own computer?

```bash
aria env pull
```

This writes the values to `.env.local` (change it with `--file`, narrow it with `--service`). It waits while you approve the request in Aria, because it reveals secrets. The file is readable only by you and is added to `.gitignore`. Never commit it or paste it into a chat.

## What can Aria AI and my coding agent do with variables?

They can read which names exist and which are missing, and they can ask you for values, which then show at the top of **Environment**. They never see a value. When either tries to change variables, it sends them for your approval first. The rules are on the [safety model](https://getaria.cloud/docs/mcp) page.

Next: [Postgres, Redis and databases on Aria](https://getaria.cloud/docs/databases)