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>. ax experiment run resolves these references server-side before injecting env vars into the sandbox. The store itself, and how references resolve: 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.

No host overrides

Runs take no overrides from your machine: only the declared value, literal or reference, applies. To change a value, edit the YAML or update the stored secret.