Environment and Auth | AXP Documentation

AXP has two separate environment surfaces:

Experiment secrets are names declared in experiment YAML and injected into variant containers.
CLI and harness environment variables configure AXP itself, such as model-provider credentials or platform API credentials.

Experiment secrets

Declare experiment secrets by name only. Values never go in the experiment file.

schema_version: 1
id: github-example
name: "GitHub example"
secrets:
  - GITHUB_TOKEN
matrix:
  variant:
    - id: default
      tag: default
    - id: extra
      tag: extra
      overrides:
        secrets:
          - PRIVATE_REGISTRY_TOKEN

Top-level secrets apply to every variant. matrix.variant[].overrides.secrets adds names for that variant only. A variant's final secret list is the top-level list followed by variant additions, with duplicate names silently merged across those two scopes.

Before a real run starts containers, AXP resolves the union of the secrets required by the selected variants. If any required name is missing, the run fails before variant execution.

Experiment secrets are injected only by local runs (axp local run). The platform path (axp run) does not yet deliver secrets and rejects any experiment that declares them — top-level or in a variant overrides.secrets — at submit. Run secret-bearing experiments with axp local run; see Running experiments.

Only experiment-declared names are copied from secret sources. If .env or an --env-file contains unrelated variables, AXP ignores them.

Secret precedence

AXP reads experiment-declared secrets from these sources, from lowest to highest precedence:

./.env, automatically discovered relative to the current working directory.
Each --env-file PATH, in command-line order. Later files override earlier files.
Host environment variables.
--env NAME=VALUE or --env NAME.

That means host environment variables override values from ./.env and explicit env files, and --env overrides everything else.

axp local run experiment.yaml \
  --env-file defaults.env \
  --env-file local.env \
  --env GITHUB_TOKEN \
  --env PRIVATE_REGISTRY_TOKEN=token-for-this-run

For --env NAME=VALUE, AXP uses the value exactly as provided. For bare --env NAME, AXP reads NAME from the host environment while parsing CLI flags; if the host variable is not set, parsing fails.

When ./.env supplies the final value for at least one declared secret, AXP prints a notice:

axp: loaded secrets from /path/to/.env

Explicit --env-file paths do not print that auto-load notice.

Valid secret names

Secret names must match:

^[A-Z_][A-Z0-9_]*$

Use uppercase ASCII letters, digits, and underscores. The first character must be an uppercase letter or underscore. Lowercase names, Unicode names, names with hyphens, and empty names are rejected.

Duplicate names inside the same secrets list are rejected. Duplicates between top-level secrets and a variant override are allowed and merge to one injected variable.

These names are reserved by the harness and cannot be declared as experiment secrets:

ANTHROPIC_API_KEY
ANTHROPIC_BASE_URL
OPENAI_API_KEY
OPENAI_BASE_URL
CURSOR_API_KEY
MODEL
MAX_TURNS
IS_SANDBOX
TRACEPARENT
any name starting with AXP_
any name starting with CLAUDE_CODE_
any name starting with CODEX_
any name starting with CURSOR_
any name starting with OTEL_

Forwarding secrets to MCP servers

Experiments that expose MCP servers to the agent can route declared secrets into those servers as stdio env entries or HTTP/SSE headers. Only secret names (and ${NAME} placeholders for headers) appear in the YAML; values come from the same resolution pipeline described above. See MCP servers for the full schema and validation rules.

Resolved secret values are written verbatim into the ACP session/new JSON-RPC frame, which is recorded in agent-events.jsonl before any redaction. Any debug bundle generated for an experiment that forwards secrets to MCP servers will contain those values — treat such bundles as sensitive.

Model credentials

axp run (the platform path) supplies model access for you — you do not set a model key. Host model credentials apply to local runs. axp local run requires a credential for each selected agent in your host environment:

agent: claude uses ANTHROPIC_API_KEY.
agent: codex uses OPENAI_API_KEY.
agent: cursor uses CURSOR_API_KEY.

export ANTHROPIC_API_KEY=...
axp local run experiment.yaml

export OPENAI_API_KEY=...
axp local run codex-experiment.yaml

export CURSOR_API_KEY=...
axp local run cursor-experiment.yaml

These names are harness-managed and reserved, so do not put them in experiment secrets. AXP reads them from the host, ./.env, --env-file, or --env, then injects only the selected agent's credential into the variant container.

ANTHROPIC_BASE_URL and OPENAI_BASE_URL are also reserved by AXP. Do not put them in experiment secrets.

AXP-provided model access

axp run always uses platform-supplied model access. For a local run, add --managed-model-access when you want AXP to supply model credentials instead of providing your own Anthropic, OpenAI, or Cursor API key. It supports agent: claude, agent: codex, and agent: cursor variants.

axp local run --managed-model-access experiment.yaml

Use --api-base-url <URL> only when the AXP team gives you a non-default platform URL, such as a preview environment:

axp local run --managed-model-access --api-base-url https://preview.example.com experiment.yaml

--api-base-url is only valid when using AXP-provided model access.

agent: cursor variants are routed through the model proxy's /cursor subpath, which forwards to Cursor's backend with the AXP-held key, so they work under --managed-model-access alongside claude and codex.

Platform credentials

AXP stores platform API credentials at:

~/.fiveonefour/axp/credentials.toml

The file stores the API key plus the email and active org returned by the platform WhoAmI RPC. AXP writes the file with 0600 permissions and re-applies that mode when saving over an existing file.

AXP_API_KEY overrides the saved API key when the CLI loads credentials:

AXP_API_KEY=... axp auth whoami

The environment override does not rewrite the saved API key in credentials.toml; it only affects that process. The saved active org is still used as the preferred org when the override key has access to it.

Platform URL

The CLI connects to the AXP platform out of the box — you do not need to configure anything. If the AXP team gives you a different platform URL, set AXP_PLATFORM_URL:

AXP_PLATFORM_URL=https://platform.example.com axp auth whoami

AXP_PLATFORM_URL starts with AXP_, so it is reserved and cannot be declared as an experiment secret.

Auth commands

axp auth connect --code axpcli_...

The cli_auth.start MCP tool creates the one-time code and returns the full command. The code can only be used once and expires quickly.

axp auth login

The CLI prompts for an API key, verifies it with the platform WhoAmI RPC, lets you select an organization when the account has multiple organizations, then saves credentials to ~/.fiveonefour/axp/credentials.toml.

Pass the key non-interactively with:

axp auth login --token ...

Show the identity resolved by the platform API:

axp auth whoami

Use JSON output for scripts:

axp auth whoami --json

List organizations visible to the current API key and show which one is active:

axp auth orgs
axp auth orgs --list --json

Switch the active CLI organization:

axp auth orgs --switch org_...

Platform commands such as axp upload, axp send-debug, axp download, and axp query use the active CLI org by default. For a one-off platform command without changing the saved active org, pass --org org_... to that command.

Log out locally:

axp auth logout

logout removes ~/.fiveonefour/axp/credentials.toml. It does not revoke the API key on the platform.

Search documentation