Env vars
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 and Vault secrets instead — those are encrypted at rest, scoped by allowed domains, and never returned by GET endpoints.
How it works
- Create a variable with
POST /agents/{agent_id}/env-vars, passing akeyand avalue. - Redeploy the agent for the variable to land in the container's environment.
- 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
- Flip a feature flag per agent in production without touching code. Set
LOG_LEVEL=debugon 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
| 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 |