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.

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.

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.