Model Providers and the 514.ax AI Gateway

Choose how runs reach models, then optionally add organization BYOK so managed traffic can use your provider keys first.

Organization BYOK is optional configuration inside managed model access, not a separate path. --local-model-keys runs skip BYOK entirely.

For experiment secrets and CLI auth, see Environment and Auth. CLI flags: AX CLI → llm-provider.

Coverage

Cursor always uses the managed Cursor path (or a host CURSOR_API_KEY for non-managed local runs).

Configure organization BYOK

Use Integrations → LLM Providers in the platform app, or ax llm-provider ….

Who can configure: organization admin via CLI (ax auth login or AX_API_KEY), or UI roles with org:llm_providers:manage (for example enterprise security).

Provider keys are a separate write-only store — not the org secret store, not host .env, and not experiment environment_variables. Putting a key in Secrets or YAML does not enable BYOK.

Claude Code gateway compatibility

On Integrations → LLM Providers, an organization toggle enables Claude Code gateway compatibility for hosted managed runs (ax experiment run).

When enabled, those Claude Code runs receive CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 so experimental beta headers and schema fields are disabled for gateway compatibility. Off by default; local runs are unchanged.

Choices that matter

For each provider, set:

1. Base URL — public http:// or https:// provider endpoint (loopback and private hosts are rejected).
2. API key — write-only; never shown again. In the CLI, prompted in an interactive terminal or read from stdin (never a flag). Leave empty on edit to keep the stored key.
3. Selected models — one or more eligible model IDs this key may serve. Create requires at least one model (repeat --model; there is no all-models option).
4. Priority — non-negative integer; lower runs first among providers that match the requested model. Priority orders providers; it does not choose the model. Omitting priority appends after the current list.

UI: test the connection before save; re-test after any URL or key change. CLI: create does not auto-probe — use test first if you want a dry run.

Create a provider

Sign in as an org admin, then create a provider. The key is prompted (or pipe it on stdin) — never pass it on the command line.

# Optional dry-run (key prompted / stdin)
ax llm-provider test --base-url https://api.anthropic.com

ax llm-provider create "Prod Anthropic" \
  --base-url https://api.anthropic.com \
  --model anthropic/claude-sonnet-4-6 \
  --model anthropic/claude-opus-4-8

ax llm-provider test --base-url https://api.openai.com

ax llm-provider create "Prod OpenAI" \
  --base-url https://api.openai.com \
  --model openai/gpt-5 \
  --model openai/gpt-5.3-codex

ax llm-provider test --base-url https://llm.example.com/v1

ax llm-provider create "Company LLM gateway" \
  --base-url https://llm.example.com/v1 \
  --model openai/gpt-5 \
  --model openai/gpt-5.3-codex

Common follow-ups:

ax llm-provider list
ax llm-provider update <provider-id> --set-key
# Listed ids lead (first = priority 0); unlisted providers keep relative order
ax llm-provider reorder <id-to-promote>
# Optional: set gateway rank on the same scale
ax llm-provider reorder <id-first> <id-second> --gateway-priority 1
ax llm-provider gateway enable
ax llm-provider gateway disable
ax llm-provider delete <provider-id> --yes
ax integrations gh connect

How routing works

On managed model access (remote, or default local without --local-model-keys), the AX model proxy builds the eligible choices from org BYOK providers whose selected models include the requested model, plus the built-in 514.ax Gateway when enabled, and tries them in priority order. Lower priority is tried first. On a tie, org BYOK is tried before the gateway.

Example: After reordering so org BYOK is priority 0 and the 514.ax Gateway is priority 1, a request for a model on that BYOK list tries your provider first. If that attempt fails in a way that allows fallback (for example auth, rate limit, timeout, or server error), the proxy tries the gateway next. Priority only sets that order — the experiment's model selection still decides which model is requested.

Defaults and guards:

• Gateway is enabled by default (priority 0 when the org has no custom settings).
• You cannot disable the gateway until the org has at least one BYOK provider.
• You cannot delete the last BYOK provider while the gateway is disabled (re-enable first).
• Only models you selected on a provider use that key; other models still use the gateway (when enabled).
• Invalid BYOK config (non-public URL, bad path, and similar) is skipped and does not fall through to the billed gateway for that request.
• OpenAI Responses sessions stick to one provider. Codex-style agents replay encrypted reasoning that only the originating OpenAI account can decrypt, so the provider that serves a run's first successful /v1/responses request is pinned for the rest of that run. Later Responses requests retry that provider on transient failures (timeout, rate limit, 5xx) instead of falling over to a different one; a persistent provider outage fails the run's requests rather than silently switching accounts mid-session.

Billing and security

• BYOK traffic uses your provider billing. 514.ax Gateway traffic is metered managed model access.
• Sandboxes get a short-lived, run-scoped credential for the AX model proxy — not your stored provider API key. Real provider auth is injected server-side.
• A custom base URL expands trust: selected-model traffic is sent to that public endpoint. Prefer endpoints you control.
• Per-run cost caps are not authorable in experiment YAML (the former limits.max_cost_usd was removed); managed model access is metered and billed per run. See Limits.

Troubleshooting

Related

• Environment and Auth — experiment secrets vs host keys vs managed model access
• AX CLI → llm-provider — ax llm-provider
• Experiment YAML → MCP servers — managed proxy refs for MCP servers that call models
• Security — isolation and credential handling
• Installation — local Docker prerequisites and managed-access alternative