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

# celesto sandbox env

> Use celesto sandbox env to set, remove, and list environment variables inside a running sandbox over SSH or the Celesto guest-agent channel.

`celesto sandbox env` manages environment variables inside a sandbox. Variables are written to the guest so new login shells and later `vm.run(...)` calls can read them.

## Synopsis

```bash theme={null}
celesto sandbox env set <sandbox> KEY=VALUE... [OPTIONS]
celesto sandbox env unset <sandbox> KEY... [OPTIONS]
celesto sandbox env list <sandbox> [OPTIONS]
```

> [!NOTE]
>
> Environment variable changes apply to new guest sessions. In an existing shell, run `source /etc/profile.d/celesto_env.sh` to reload them.

## Shared options

**--ssh-key** `string`

Path to an SSH private key when the command uses SSH.

**--ssh-user** `string` (default: root)

SSH user when the command uses SSH.

**--comm-channel** `string`

Host-to-guest control channel. Use `ssh`, `vsock`, or omit it for auto-selection.

**--json** `flag`

Print a JSON envelope instead of formatted text.

## set

Set one or more variables:

```bash theme={null}
celesto sandbox env set my-sandbox \
  OPENAI_API_KEY=sk-... \
  MODEL=gpt-4.1
```

Force vsock for a recent Linux image:

```bash theme={null}
celesto sandbox env set my-sandbox APP_ENV=prod --comm-channel vsock
```

## unset

Remove variables:

```bash theme={null}
celesto sandbox env unset my-sandbox OPENAI_API_KEY MODEL
```

## list

List variable names with values masked:

```bash theme={null}
celesto sandbox env list my-sandbox
```

Show values when you are in a safe terminal:

```bash theme={null}
celesto sandbox env list my-sandbox --show-values
```

## Key rules

Environment variable names must be valid shell identifiers, such as `OPENAI_API_KEY` or `APP_ENV`. Use `KEY=VALUE` pairs for `set`; values may be empty strings.

## Security notes

> [!WARNING]
>
> Environment variables are stored in plaintext inside the sandbox. Avoid printing sensitive values in logs, and rotate credentials after sharing a sandbox with another workflow.

## Related commands

* [`celesto sandbox shell`](https://celesto.ai/docs/celesto/cli/shell) - Open a shell that can read the variables
* [`celesto sandbox file`](https://celesto.ai/docs/celesto/cli/file) - Copy config files into a sandbox
* [Control channel](https://celesto.ai/docs/celesto/concepts/control-channel.md) - Learn when Celesto uses SSH or vsock


## Related topics

- [celesto sandbox file](https://celesto.ai/docs/celesto/cli/file.md)
- [Windows sandboxes in Celesto](https://celesto.ai/docs/celesto/guides/windows-guests.md)
- [Environment variables in Celesto sandboxes](https://celesto.ai/docs/celesto/guides/environment-variables.md)
- [celesto sandbox create](https://celesto.ai/docs/celesto/cli/create.md)
- [celesto sandbox list](https://celesto.ai/docs/celesto/cli/list.md)


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