English documentation · runtime 7.24.4 · SDK 2.6.7. Content is maintained with runtime development; see each guide's scope and review date.

Custom and Gateway Providers

Status: Active Scope: current-state Last reviewed: 2026-09-06 Owner: ax-code runtime

AX Code talks to models through standard provider protocols. Any endpoint that speaks an OpenAI-compatible (/v1/chat/completions) or Anthropic-compatible (/v1/messages) API can be added as a custom provider by pointing baseURL at it — no code changes and no waiting for a built-in preset.

This covers self-hosted aggregators and relay gateways such as LiteLLM, one-api, new-api, and the Vercel AI Gateway, as well as private corporate proxies and any other compatible service. AX Code treats these uniformly: it speaks the wire protocol, you supply the URL and key.

Responsibility note. A gateway sits between AX Code and the upstream model, so your prompts, code, and credentials pass through it. When you point AX Code at a third-party or account-pooling relay, you are responsible for trusting that operator with your data and for staying within the terms of service of every upstream provider it routes to. Built-in gateway presets such as OpenRouter use the same standard protocol path; custom gateway configuration does not imply endorsement of any relay operator.

Interactive setup

Use /connect -> API Cloud Provider -> Custom API provider for a compatible gateway, or /connect -> AX Trust -> Connect AX Trust for an AX Trust gateway. Enter its base URL (including /v1 for AX Trust) and client API key. The editor discovers model IDs and metadata and stores credentials in encrypted auth storage. It can also accept explicit model IDs if discovery is unavailable. Reconnecting a saved URL retains its provider ID and key when the token is left blank. AX Trust connections keep their category after edits and model refreshes. AX Code sends X-AX-Prompt-Cache-Key with the session ID on those connections so the gateway can keep a session on one eligible account; set provider.<id>.options.axTrust to false to disable it. This header is not forwarded upstream and is not a body prompt_cache_key.

Connected AX Trust providers refresh their model lists in the background on startup. AX Code calls the configured endpoint’s GET /models with the existing credential and updates model names, context/output limits, reasoning, tool calling, temperature support, and image support. Image-capable models display the vision marker in /models, including gateway aliases when AX Trust advertises their image support. The TUI updates when discovery completes. For exact first-party DeepSeek model IDs, missing metadata is filled from the bundled models.dev catalog. Explicit gateway capability flags and limits take precedence; unknown aliases do not inherit capabilities by name similarity.

A successful refresh replaces the runtime list, removing models no longer advertised by the gateway, and still applies configured allow/block lists. Timeouts, errors, empty or invalid responses retain the saved list and log a discovery failure. Startup does not wait for the network. This refresh does not rewrite provider configuration or credentials; the saved configuration remains the startup fallback. Ordinary custom API providers retain manual refresh.

How a provider is resolved

For each request AX Code needs three things from a provider entry:

• npm — the AI SDK adapter that speaks the wire protocol. Use @ai-sdk/openai-compatible for OpenAI-style endpoints and @ai-sdk/anthropic for Anthropic-style endpoints. Only @ai-sdk/* adapters are bundled/installable.
• options.baseURL — the gateway URL. Falls back to the provider api field, then to the model’s own api.url. Supports ${ENV_VAR} substitution.
• A credential — resolved in order from options.apiKey, then the persisted auth store, then the provider’s env variables.

Manual configuration also needs an explicit models map. The interactive editor populates this map from the endpoint or from model IDs you provide.

Dedicated private GPU clouds are first-class providers under /connect → Private GPU cloud. Paste the OpenAI-compatible URL and token (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti, or custom-private-gpu); AX Code calls GET …/models and uses the deployed model IDs automatically.

Hosted GPU catalogs (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) use an API key and the bundled model snapshot, the same pattern OpenCode uses.

OpenAI-compatible gateway

Most aggregators (LiteLLM, one-api, new-api, free/self-hosted gateways) expose an OpenAI-compatible surface. Add this to your ax-code.json (global at ~/.config/ax-code/ax-code.json, or per-project at the repo root):

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

• The key "my-gateway" is the provider id you select in /connect and ax-code models.
• Each key under models is the local selection ID. Set the entry’s id to the exact model ID the gateway expects when it differs from that key; otherwise the key is used for manually declared models without an existing catalog mapping.
• Prefer ${ENV_VAR} over a literal key so the secret stays out of committed config.

Gateway model aliases after changing endpoints

Changing options.baseURL does not translate manually configured model IDs. For example, an AX Trust endpoint may advertise deepseek-flash while an existing local selection is ax-trust/deepseek-v4-flash. Keep the local key and set provider.ax-trust.models.deepseek-v4-flash.id to deepseek-flash. AX Code then sends the gateway ID in API requests.

See the AX Trust DeepSeek Flash configuration example. Merge the relevant provider fields into your existing configuration, preserving other models and their capability settings. The example uses {env:AX_TRUST_API_KEY}; set that environment variable before starting AX Code, or keep your existing credential configuration. Restart AX Code after editing.

When diagnosing 403 model is not allowed, compare the request’s model ID with the endpoint’s authenticated GET /models response. A successful model list request alone does not establish permission to run a model. If the exact ID still fails, check the gateway’s key/model permissions.

Anthropic-compatible gateway

Relays that expose /v1/messages (the Claude API shape) use the Anthropic adapter:

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

Some Anthropic-shaped relays also honor the Claude environment variables directly. For a quick headless run without editing config you can set:

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

A config entry is still recommended when you want the gateway to appear as its own selectable provider with a curated model list.

Model fields

Model entries reuse the registry schema; for a custom endpoint the useful fields are:

Set capability flags to match what the upstream model actually supports; AX Code uses them to gate tool calls, attachments, and context budgeting.

Verifying

After saving config:

• ax-code models lists every model your provider exposes.
• /connect inside the TUI shows the provider and lets you authenticate if you used an env key instead of options.apiKey.

If a model is missing, confirm the provider id, the model key, and that the gateway is reachable at baseURL.

Troubleshooting

• Auth errors — confirm the credential resolution order: options.apiKey wins, otherwise an env/auth-store key is used.
• Stalled streams — gateways sometimes buffer SSE. Tune options.chunkTimeout (per-chunk) and options.timeout (whole request) on the provider.
• Tool calls rejected — set "tool_call": true on the model and confirm the upstream model behind the gateway actually supports tools.