A secret is a named value, such as an npm token or an API key, stored in your account. Environments refer to it by name, so the value never appears in git.

## Add a secret

- **Dashboard:** open **Environments > Secrets** and choose **New secrets**.
- **CLI:** `ellipsis variable set NPM_TOKEN=your-token-value`, or `ellipsis variable set -f .env` to load a file.
- **API:** `PUT /v1/secrets`:

```bash
curl -X PUT https://api.ellipsis.dev/v1/secrets -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" -H "Content-Type: application/json" -d '{"secrets": [{"name": "NPM_TOKEN", "value": "your-token-value"}]}'
```

Setting an existing name replaces its value. Names use letters, digits, and underscores, and can't start with a digit. An account can store up to 500 secrets.

## Use a secret

List its name under `variables` without a `value`:

```yaml title=".ellipsis/environments/private-packages.yaml"
ellipsis:
  kind: environment
  name: private-packages

repositories:
  - name: web-repo

variables:
  - name: NPM_TOKEN
```

Setup scripts and the agent get `NPM_TOKEN` as an environment variable. A missing secret fails the session.

To pass a secret to an [MCP server](/docs/environments/schema#add-an-mcp-server), write `${NAME}` in its `headers` or `env`. It doesn't need a `variables` entry.

## Rules

- Secrets belong to the account, so any environment can use them.
- Stored values can't be read back through the dashboard, CLI, or API; you see names only.
- The agent can read every secret its environment sets. Keep values out of prompts and command output; see [Permissions](/docs/permissions#secrets).
- Delete a secret in the dashboard, with `ellipsis variable delete NPM_TOKEN`, or with `DELETE /v1/secrets/{name}`.