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

# Environments

> Store the variables and secrets your cloud sessions' tools need in a workspace Environment, and load it into a run with --env.

<Note>
  **Early access.** Cloud sessions and managed agent runs are not open to every account yet: we are
  letting accounts in gradually while we test. They run in a cloud sandbox operated by Mutagent, so
  there is nothing to host. A sandbox with nothing to do for 15 minutes stops; send the session a
  message and it wakes up, delivers your message and carries on in the same conversation.
</Note>

An Environment holds the variables and secrets your cloud sessions need: a GitHub token, a database
URL, a feature flag. Your local shell variables are not sent to the sandbox, so anything a tool reads
from its environment goes into an Environment.

Do not put model keys in an Environment. They come from your [LLM providers](/helix/cloud/setup).

Before you start: sign in and select a workspace (see [LLM providers and models](/helix/cloud/setup#before-you-start)).
Environments belong to one workspace. Pass `--workspace <name>` to work in another one for a single
command.

## Create an Environment and use it

Put secrets in a file in `.env` format (`KEY=VALUE` lines) and keep them off the command line:

```bash theme={null}
mutagent env set demo GREETING=hello --secrets-from-file .env.demo.secrets --json
mutagent helix agent "You write short greetings." --env demo -p "Read GREETING and use it in a greeting."
```

`env set` creates the Environment if it does not exist and adds the entries. `--env demo` loads them
into the sandbox as environment variables when the session starts.

With `--json`, `env set` returns `created` (true when this command made the Environment),
`variables` and `secrets` (the names stored as each). Check that every name landed where you meant
it to. The command exits 0 on success. `--secret KEY=VALUE` on the command line also works, but
the value stays in your shell history.

## Variables and secrets

Positional `KEY=VALUE` entries are variables. `--secret KEY=VALUE` entries are secrets. A name cannot
be both. A value may contain `=`; the split is at the first one. `--secret` takes every `KEY=VALUE`
that follows it, so put variables before `--secret`.

| | Variables | Secrets |
| - | - | - |
| Set with | `KEY=VALUE`, `--from-file <path>` | `--secret KEY=VALUE`, `--secrets-from-file <path>` |
| Stored | As written | Encrypted |
| In the sandbox | Environment variable | Environment variable |
| Read back | Name and fingerprint only | Name and fingerprint only |

## Load entries from files

```bash theme={null}
mutagent env set staging --from-file .env.staging --secrets-from-file .env.staging.secrets
```

The CLI reads the files on your machine and sends their entries. A value on the command line wins
over the same name in a file.

`env set` merges: entries you do not name stay. `--replace` replaces the whole Environment and
removes every entry you did not name, secrets included, so it also needs `--force`. Without
`--force` it refuses with `CONFIRMATION_REQUIRED` (exit 1), names the entries it would remove, and
writes nothing:

```bash theme={null}
mutagent env set staging --replace --from-file .env.staging --force
```

## Manage Environments

| Command | What it does |
| - | - |
| `mutagent env ls` | List Environments and their entry counts. `mutagent env list` is the same command. |
| `mutagent env show <name>` | List entry names, kinds, and a fingerprint of each value. |
| `mutagent env set <name> …` | Create or merge entries. `--replace --force` replaces the whole Environment. |
| `mutagent env unset <name> <KEY>… --force` | Remove entries. A name that is not there is not an error. Requires `--force`. |
| `mutagent env rm <name> --force` | Delete the Environment and its secrets. `mutagent env delete` is the same command. |

Stored values are never returned. The fingerprint is 8 hex characters computed on the server with a
key only the server holds. It stays the same while the value is unchanged, so comparing two `show`
runs tells you whether a value changed. You cannot compute it yourself; to be sure a value is right,
set it again.

A change applies to sessions that start after it; a running session keeps the values it started
with.

Environment names use letters, digits, `.`, `_`, and `-`, up to 64 characters. Entry names use
uppercase letters, digits, and `_`, and cannot start with a digit. An Environment holds up to 64 KiB.

## Which value is used

A sandbox receives environment variables from up to three sources. When two set the same name, the
later one is used:

| Order | Source | What it sets |
| - | - | - |
| 1 | The workspace's LLM providers | Model keys, such as `ANTHROPIC_API_KEY`. |
| 2 | The Environment named with `--env` | Your variables and secrets. |
| 3 | Values an API client sets for one session | Values for that session only. The CLI has no flag for this. |

A few names are set by the platform in every sandbox and always keep the platform's value. An
Environment cannot store one: saving it is refused, and the error names the entry. Rename it.

## Overriding a model key

`env set` refuses a variable named like an LLM provider key, such as `ANTHROPIC_API_KEY`, because it
would replace the workspace key in every run that loads the Environment. If you need that override,
pass `--allow-provider-key` and store the value as a secret. It does not add models to
`mutagent helix models` or change the default.

## If it fails

| Exit code or error | Fix |
| - | - |
| Exit 3 | Not signed in or no workspace. Run `mutagent login`, then `mutagent workspaces use <name>`. |
| Exit 1, invalid name | Entry names use `A-Z`, `0-9` and `_`, and cannot start with a digit. The error names the entry, never the value. |
| Exit 1, the name looks like an LLM provider key | See [Overriding a model key](#overriding-a-model-key). |
| `CONFIRMATION_REQUIRED` (exit 1) | `--replace`, `env unset` and `env delete` need `--force`. Confirm with the user first. |
| A run with `--env <name>` fails | Check the name with `mutagent env list --json` in the same workspace. |

More in [Troubleshooting cloud runs](/helix/cloud/troubleshooting#environments).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.