Search documentation

Search the Fumadocs-backed documentation index.

Environment variables

Literal config and ax://secrets references injected into every variant.

environment_variables injects environment variables into variants at runtime. Use it for non-secret runtime configuration and supported secret references. Names and values are visible to the agent; do not use them to announce that the run is a test. See Experiment design.

environment_variables:
  - name: LOG_LEVEL
    value: debug
  - name: GITHUB_TOKEN
    value: ax://secrets/prod-gh
  - name: DATABASE_URL
    value: ax://secrets/staging-db

Environment variable object

FieldRequiredType / valuesNotes
nameYesEnv-var nameMust match ^[A-Z_][A-Z0-9_]*$. Harness-reserved names and prefixes are rejected.
valueYesStringLiteral value or ax://secrets/<slug> reference (legacy axp://secrets/<slug> is also accepted). Other values beginning with ax:// or axp:// are rejected.

Store secret values once with ax secret set <slug>, then reference them with ax://secrets/<slug>. Both remote and local ax experiment run invocations resolve these references before injecting env vars into the sandbox. The store itself, and how references resolve on each run path: Secrets.

A referenced slug that does not exist in your org fails at preflight.

Reserved names

A name must match ^[A-Z_][A-Z0-9_]*$: uppercase ASCII letters, digits, and underscores, starting with a letter or underscore. Lowercase, Unicode, hyphenated, empty, and duplicate names are rejected.

Avoid the following environment variable names and prefixes. These are reserved for internal AX CLI use:

  • ANTHROPIC_API_KEY
  • ANTHROPIC_BASE_URL
  • OPENAI_API_KEY
  • OPENAI_BASE_URL
  • CURSOR_API_KEY
  • MODEL
  • MAX_TURNS
  • IS_SANDBOX
  • TRACEPARENT
  • any name beginning with AX_, AXP_, CLAUDE_CODE_, CODEX_, CURSOR_, or OTEL_

CLI and platform configuration such as AX_API_KEY and AX_PLATFORM_URL falls under the AX_ prefix: set those in your shell, never in experiment YAML.

A few of these — MODEL, MAX_TURNS, and IS_SANDBOX — are reserved even though the harness never sets them. Generic, un-namespaced names like these in an agent's environment are a signal that the agent is being evaluated rather than doing ordinary work, so the harness delivers those controls over the agent's own interfaces instead. Reserving the names keeps an experiment from putting the signal back.

Local overrides

On ax experiment run --local, local sources can override any declared value, literal or reference, by env-var name. Lowest to highest precedence:

  1. ./.env in the current working directory
  2. Each --env-file PATH, in command-line order (later wins)
  3. Host environment variables
  4. --env NAME=VALUE, or --env NAME to read NAME from the host (fails if unset)
# Override LOG_LEVEL and forward GITHUB_TOKEN from the host for one local run
ax experiment run experiment.yaml --local \
  --env-file local.env \
  --env GITHUB_TOKEN \
  --env LOG_LEVEL=trace

Only names the experiment declares are read; unrelated keys in .env or --env-file are ignored. Override values are always literal: they are injected as written, never re-resolved as references. Remote runs take no overrides; --env and --env-file are local-only flags.