# Computer environment variables

> The -e grammar, how references resolve, when changes reach a computer, and limits

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/reference/computer-env

This page describes how a computer's environment is built from literals,
variables and secrets. For the procedures, see
[Give computers secrets and variables](https://nevia.cloud/docs/workspaces/secrets-and-variables.md).

## The `-e` grammar

`nevia new`, `nevia set` and `nevia exec` take the same forms:

| Form                        | Result                                                           |
| --------------------------- | ---------------------------------------------------------------- |
| `-e KEY=value`              | A literal value                                                  |
| `-e secrets.NAME`           | `NAME` set from the secret, short for `-e NAME={{secrets.NAME}}` |
| `-e variables.NAME`         | `NAME` set from the variable                                     |
| `-e KEY={{secrets.NAME}}`   | `KEY` set from the secret                                        |
| `-e KEY={{variables.NAME}}` | `KEY` set from the variable                                      |

A reference may sit inside a longer value, such as
`postgres://app:{{secrets.DB_PASSWORD}}@db:5432/app`. Spaces inside the braces
are allowed: `{{ secrets.NAME }}`. Escape literal braces as `\{\{` and `\}\}`;
`-e 'JSON=\{\{x\}\}'` gives `{{x}}`. A lone `{` or `}}` is plain text.

## Names

An env name is letters, digits and `_`, and does not start with a digit.
Reserved names: `NEVIA_*`, `LD_*`, `PATH`, `HOME`, `USER`, `SHELL`, `PWD`,
`HOSTNAME` and `TERM`.

## Checks and failures

The CLI rejects a malformed template or an invalid variable name before it sends
any request. A secret or variable that does not exist in the workspace fails at
the API (`400` on `env.NAME`), and the CLI names the `nevia secrets` or
`nevia variables` command that creates it; there is no fallback to the local
shell environment. Giving the same name twice is refused.

Interactive sessions (`nevia exec -i` or `-t`) take the same `-e` forms and
escapes as one-shot exec; the API interprets them.

## API requests

The API takes the same `{{secrets.NAME}}` and `{{variables.NAME}}` templates
in `env`. A secret resolves to its value and a variable to its current value.

A create or update that names an unknown secret or variable fails with `400`,
and `details.missing` names it. An exec reports the same with `409`.

`PATCH` merges env. A var given replaces that name, `null` detaches it, and
vars not named are kept. Nothing restarts; the next exec uses it.

`POST .../exec` and `POST .../stream` take `env` as extra values for that run.
Nothing is stored, and an extra value wins over the stored env for the same name.

## Where the env applies

A computer's env is stored by Nevia, not in the machine. Every `nevia exec`,
including `-i` and `-t` sessions, runs with it: the image's env, then the
computer's stored env, then `exec -e`, the later one winning for the same name.
The computer's own startup process does not see it. `TERM` is reserved and the
API refuses it in env; `-t` sets it (`xterm-256color`, or `dumb`), and
`COLORTERM` from your terminal unless the computer's env or `-e` sets it. A
session keeps room for both in the env limits, so it takes at most 126
variables, two fewer than a one-shot exec, and its names and values total at
most 256 KiB less 91 bytes. Session details are in
[Interactive sessions](https://nevia.cloud/docs/workspaces/secrets-and-variables.md#interactive-sessions).

References are stored by name and resolve at every exec:

| Source    | Resolved                                                | Effect of later changes           |
| --------- | ------------------------------------------------------- | --------------------------------- |
| Variable  | Its current value, at every exec.                       | An edit reaches the next exec.    |
| Secret    | Its current value, at every exec.                       | A rotation reaches the next exec. |
| `exec -e` | Per run; nothing is stored.                             | None.                             |
| Branch    | The source computer's stored env is copied.             | Same rules as above.              |
| Restore   | The checkpoint's stored env is copied, as for a branch. | Same rules as above.              |

Processes already running keep the values they started with, and so do
processes resumed from memory by a restore.

Change a computer's env with [`nevia set`](https://nevia.cloud/docs/reference/cli/set.md):
`-e NAME=value` adds or replaces a var, `--unset-env NAME` removes it, and the
rest is kept. Nothing restarts; the next exec uses it.

## What deleting does

Deleting a secret or variable never blocks, and Nevia does not track which
computers use it.

* A computer whose stored env references it fails its next exec with
  `409 invalid_state`, naming the var and the missing secret or variable. Fix
  it by creating the secret or variable again under the same name, which the
  reference then picks up, or by detaching the var with
  `nevia set CMP --unset-env NAME`. At a terminal, `nevia exec` offers to
  detach it for you; it never detaches on its own, `--yes` included.
* A create, `set` or exec that names the deleted entry fails with `400`.
* Branch and restore never fail because of a delete; the new computer's execs
  fail the same way until the reference is fixed.
* A process that already started with the value keeps it, and so does a
  computer restored from a checkpoint taken while one ran. Deleting is not
  revocation: revoke the credential at its source as well.

## Limits

A computer's env, and its env merged with an `exec -e` at each exec, hold at
most 128 variables, 64 secret references, 8 KiB per value, and 256 KiB of
names and values in total. A secret's or a variable's value is at most 8 KiB. A
value's size with its secrets is only known at exec: one that grows past 8 KiB as its
secrets change fails the exec with `409 invalid_state` until the secrets are
shortened or the var is replaced or detached. Secrets and
variables count together toward a per-workspace limit; exceeding it fails with
`409 limit_exceeded`. A secret and a variable cannot share a name.

## Viewing a computer's env

[`nevia status`](https://nevia.cloud/docs/reference/cli/status.md) shows a computer's env names only.
Secret-backed names are marked `(secret)`, and a name whose secret or variable
was deleted `(missing)`. Values, and which secret a name refers to, are never
shown.

A computer created before env was stored keeps the env its machine was created
with. That env is not shown and cannot be detached; set a var of the same name
to override it.

## Permissions

A computer's env that references a secret needs `editor` on the workspace; one
that references only variables needs `viewer`. Literal values need nothing
extra. See [Workspace permissions](https://nevia.cloud/docs/reference/workspace-permissions.md).