> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolvingmachines.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Store env secrets once and attach them to jobs by name.

An env secret is a value stored under a name, with a delivery mode. Values are write-only: every read returns metadata, never the value.

```bash theme={null}
printf %s "$GITHUB_TOKEN" | evolve secrets set GITHUB_TOKEN --delivery direct
```

Pipe the value on stdin, as above, to keep it out of your shell history; `--value <value>` is the other channel. `--delivery` is required: `direct` places the value in the sandbox environment, `brokered` keeps it out of every sandbox and needs the `--allowed-host`, `--allowed-path-prefix` and `--allowed-method` scoping. Eval trials take `direct` secrets only; a brokered one is refused with `secret_brokered_unsupported`. `--label <label>` keeps several values of one name side by side; the default label is `default`.

Restating the same value re-shapes its delivery or scoping. A different value under an existing name and label is refused with `secret_exists`: delete it first, or use another label.

```bash theme={null}
evolve secrets list
evolve secrets delete GITHUB_TOKEN --label staging
```

## Attach a secret to a job

```bash theme={null}
evolve run \
  -d terminal-bench-4@4.0 \
  -a codex \
  -m gpt-6-astra \
  --secret GITHUB_TOKEN \
  -l 5 \
  --watch
```

`--secret NAME[@LABEL][=ENVNAME]` attaches a stored secret to every agent run. `@LABEL` picks a labeled row; omitted, the `default` row or the only row, and several labels with no `default` is refused with `secret_ambiguous`. `=ENVNAME` renames the variable inside the sandbox; a name the platform owns, such as the `EVOLVE_` prefix or `REWARDKIT_JUDGE`, is refused. The job stores a reference, and the value never rides the command line.

In the SDK the same attachment is `secrets: [{ name, label?, as? }]` on `jobs().start()`. `--secret-inline NAME[@LABEL]:DELIVERY=VALUE`, or `{ name, value, delivery, label?, as? }` in that list, saves the value and attaches it in one step; re-running with the same value converges, a different value is refused with `secret_exists`.

A task's `[environment.env]` can ask for a secret with a `${VAR}` template, satisfied by a secret attached under that env name; see [tasks](/core-concepts/tasks#environment-variables). Plain, non-secret environment does not go on a job: the server refuses `agent_env` (`--ae`). Declare it in the task's `[environment.env]` table instead.

<Card title="secrets reference" icon="terminal" href="/cli-reference/secrets">
  Every flag of `evolve secrets`.
</Card>