The -e grammar, how references resolve, when changes reach a computer, and limits
This page describes how a computer's environment is built from literals, variables and secrets. For the procedures, see Give computers secrets and variables.
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.
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:
-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 withnevia set CMP --unset-env NAME. At a terminal,nevia execoffers to detach it for you; it never detaches on its own,--yesincluded. - A create,
setor exec that names the deleted entry fails with400. - 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 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.