Overview

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

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

• 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