---
title: Secrets and environment
description: Give sandboxes API keys, passwords and configuration through the encrypted vault or plain environment variables.
---

A sandbox's commands see the environment variables you give it when you create it. There are two ways to set them:

- **Vault entries** (`--secret NAME`) for API keys, passwords and tokens. Their values are stored encrypted, never shown again and never pass through your command line.
- **Environment variables** (`--env`, `--env-file`) for ordinary configuration.

Both reach the sandbox the same way: as environment variables of every command that runs in it.

## The vault

Every org has a vault of passwords and environment variables. You manage it on your [account page](https://my.pols.so/account), logged in with your email:

- **Add** an entry with a name, a kind (`password` or `env`) and a value. The name is the environment variable a sandbox gets.
- **Replace** a value by saving the same name again.
- **Delete** an entry.

A saved value is never displayed again, on the page or anywhere else, and never written to a log. The vault holds up to 100 entries of up to 32 KiB each.

API keys cannot add, change or read values. With an API key you can only list the entries' names and kinds, and name entries when you create or fork a sandbox:

```sh
pols vault ls
pols new --name agent --secret ANTHROPIC_API_KEY --secret GITHUB_TOKEN
pols fork agent --name agent-2 --secret EXTRA_TOKEN
```

The same is available as `GET /v1/vault` and the `secrets` field of `POST /v1/sandboxes` and `.../fork`, the MCP tool `vault_list` and the `secrets` argument of `sandbox_create`, and `pols.vault.list()` in the TypeScript client. Every name must exist in the vault; otherwise the call fails with `bad_request`. A sandbox lists the names it got in `secrets`.

### When values are read

A sandbox gets each entry's value when its VM is created, and keeps that value:

- Changing an entry later reaches only sandboxes created after the change.
- A fork keeps its source's entries, with the values the source got, and reads the entries you add.
- If an entry is deleted before the sandbox's VM was created, the sandbox goes to `error`.
- [Templates](/sandboxes/templates/) keep no environment, so they keep no vault values either.

### How values are protected

Values are encrypted with AES-256-GCM. The key is kept outside the database, and each value is bound to its org and name, so a ciphertext copied to another entry or org does not decrypt.

Inside a sandbox, a vault value is an ordinary environment variable: every program that runs there can read it. Give a sandbox only the secrets it needs, and do not use vault values in sandboxes that run code you do not trust.

## Plain environment variables

```sh
pols new --name app --env NODE_ENV=production
pols new --name app --env DATABASE_URL            # copies DATABASE_URL from your environment
pols new --name app --env-file .env               # KEY=VALUE lines
```

`--env KEY` copies the variable from your own environment, so its value does not appear on the command line. `--env KEY=VALUE` puts the value into your shell history and the process list; prefer the vault for anything secret. `--env-file` reads `KEY=VALUE` lines; `--env` wins over a file.

Environment variables are stored as given and returned only by name (`env_keys`). Deleting a sandbox erases them. Forks keep them; templates do not.

For a single command, `pols exec --env KEY=VALUE` adds a variable to that command only.