# Overview

What environment variables are and when to use them instead of vault secrets.



**Environment variables** are plaintext key/value pairs injected into an agent's container at runtime. They scope to a single agent — each agent has its own set, managed under `/agents/{agent_id}/env-vars`.

Env vars are the right choice for **non-sensitive configuration**: build flags, feature toggles, log levels, region codes, etc. For anything secret (API keys, tokens, passwords), use [Vaults](/api/vaults/overview) and [Vault secrets](/api/vault-secrets/overview) instead — those are encrypted at rest, scoped by allowed domains, and never returned by `GET` endpoints.

## How it works [#how-it-works]

1. Create a variable with `POST /agents/{agent_id}/env-vars`, passing a `key` and a `value`.
2. Redeploy the agent for the variable to land in the container's environment.
3. Update or delete the variable any time with the matching endpoint. Changes require a redeploy to take effect.

Variable names must match `[A-Za-z_][A-Za-z0-9_]*` and cannot start with `NAIRI_` or `CCAGENT_` (those prefixes are reserved by the platform).

## When to use it [#when-to-use-it]

* **Flip a feature flag per agent in production without touching code.** Set `LOG_LEVEL=debug` on a misbehaving agent, or roll out a feature to one tenant first via a per-agent env var.
* **Pass non-sensitive configuration to scripts the agent runs.** Region codes, build flags, model picks, anything else your skills or hooks read from `process.env` / `os.environ`.

## Env vars vs. vault secrets [#env-vars-vs-vault-secrets]

| Concern            | Env var             | Vault secret                              |
| ------------------ | ------------------- | ----------------------------------------- |
| Storage            | Plaintext           | Encrypted at rest                         |
| Scope              | One agent           | Shared across agents via vault attachment |
| Returned by `GET`  | Yes (value visible) | No (value never returned)                 |
| Domain restriction | No                  | Yes (`allowed_domains`)                   |
| Use for            | Config              | Secrets                                   |