Skip to main content

Catalog Reference

Ante resolves every provider and model from a catalog: the built-in presets documented here, with your ~/.ante/catalog.json merged on top at startup. The catalog is read once per process — restart Ante to pick up edits.

This page is the exhaustive reference. For sign-in and API-key setup, see Connect a provider. For configuration examples, jump to Custom catalog.

Built-in providers​

The presets below match v0.3.2: 15 hosted-provider presets, plus local when an offline server is running.

ProviderkeyWire styleCredential
AnthropicanthropicAnthropicMessageANTHROPIC_API_KEY
Anthropic Subscriptionanthropic-subscriptionAnthropicMessageOAuth (anthropic)
OpenAIopenaiOpenAiResponseOPENAI_API_KEY
OpenAI Compatibleopenai-compatibleOpenAiCompatibleOPENAI_COMPATIBLE_API_KEY
OpenAI Subscriptionopenai-subscriptionOpenAiResponseOAuth (openai)
GeminigeminiGeminiGEMINI_API_KEY
Vertex AI Geminivertex-geminiGeminiVERTEX_GEMINI_API_KEY
Open RouteropenrouterOpenAiCompatibleOPENROUTER_API_KEY
Open Router Responsesopenrouter-responsesOpenAiResponseOPENROUTER_API_KEY
Open Router Anthropicopenrouter-anthropicAnthropicMessageOPENROUTER_API_KEY
Grok (xAI)xaiOpenAiResponseXAI_API_KEY
ZaizaiOpenAiCompatibleZAI_API_KEY
DeepSeekdeepseekOpenAiCompatibleDEEPSEEK_API_KEY
MiniMaxminimaxOpenAiCompatibleMINIMAX_API_KEY
AntixantixAnthropicMessageOAuth (antix), then ANTIX_API_KEY
LocallocalOpenAiCompatiblenone

The key column is what you pass to --provider. An API-key provider reads its environment variable first, then a key stored with ante auth add <key> or pasted in /providers. An OAuth provider signs in from /providers in the TUI or with ante auth login <key> from the CLI. antix takes either: an Antix sign-in first, then ANTIX_API_KEY, then a stored key. See Credentials for how to change any of this.

Models by provider​

Each provider ships a set of preferred_models — the ids that appear in the model picker. When you select a provider without naming a model, Ante defaults to its heaviest-weight model (see Weight classes), not simply the first in the list. Explicit provider choices are authoritative: if you pass --provider, Ante sends the model id you supplied to that provider even when it is not listed in preferred_models (see Resolution).

Anthropic​

anthropic and anthropic-subscription serve the same models:

ModelDescriptionContext
claude-haiku-5-5Fast, efficient model for high-volume agentic work1M
claude-sonnet-5-5Best combination of speed and intelligence1M
claude-opus-5-5Long-running agentic coding and knowledge work1M
claude-fable-5-1Highest capability for demanding reasoning1M
ante --provider anthropic --model claude-sonnet-5-5

OpenAI​

ModelDescriptionContext
gpt-6-astraOpenAI's most capable model for complex agentic work1.05M
gpt-6.1-solGPT-6.1 Sol for complex coding and agentic workflows1.05M
gpt-6.1-terraGPT-6.1 Terra for visual reasoning, computer use, and writing1.05M
gpt-6-lunaGPT-6 model for focused, high-volume tasks1.05M
ante --provider openai --model gpt-6.1-sol

The openai-subscription provider (ChatGPT/Codex OAuth) offers gpt-6-astra (the default, 272K context), gpt-6.1-sol and gpt-6.1-terra (500K), and gpt-6-luna (272K), all with image input. gpt-6-luna is its lightest model, so it handles auxiliary calls.

OpenAI transports​

The openai and openai-subscription providers can stream responses two ways:

TransportEndpointDefault
http_sse (HTTP + SSE)https://api.openai.com/v1/responses (or the subscription equivalent)✅
websocket_auto (persistent WebSocket)wss://.../v1/responsesopt-in

WebSocket mode keeps one connection open per session and continues each turn with previous_response_id plus only the new input items. In long agentic tool loops this eliminates per-turn round-trip latency. See OpenAI's WebSocket mode guide for the underlying protocol.

Opt in via the process-scoped env var (default is http_sse):

ANTE_OPENAI_TRANSPORT=websocket_auto ante --provider openai --model gpt-6-luna

Accepted values: http_sse, websocket_auto. Unknown values warn and fall back to http_sse.

Notes:

  • All model-generation calls use the streaming transport, including TUI turns, headless tasks, compaction, goal judging, and ambient hints. Calls that need a complete response collect that stream, so they can also use WebSocket when enabled. Cancelling a WebSocket call discards its connection so the next request cannot read the abandoned response.

  • Eligible WebSocket failures fall back to HTTP/SSE within the remaining call budget; falling back does not reset the deadline. If the budget expires, the call reports a timeout. Auth failures (401/403) disable WebSocket for the rest of the session.

  • Works against both api.openai.com (API-key) and the ChatGPT subscription backend at chatgpt.com/backend-api/codex.

  • To verify which transport is active: in debug builds, toggle the debug panel (Ctrl+L) and check the Info tab for the OpenAI Transport: line. Otherwise grep your session log for transport selected:

    grep "transport selected" ~/.ante/logs/*/ante.*.log

Gemini​

gemini and vertex-gemini serve the same models:

ModelDescriptionContext
gemini-3.8-flashGemini 3.8 Flash for long-horizon coding and autonomous agents1.05M
gemini-4-argonGemini 4 Argon for complex reasoning and autonomous agents1.05M
gemini-3.5-flash-liteFastest, lowest-cost Gemini 3.5 model for high-throughput work1M
ante --provider gemini --model gemini-3.8-flash

With no model supplied by CLI flags or settings, --provider gemini or --provider vertex-gemini selects the heaviest model, Gemini 4 Argon. Its native preset allows up to 32,768 output tokens; the OpenRouter google/gemini-4-argon preset allows 65,536. Both support image input and low, medium, and high effort.

Grok (xAI)​

ModelDescriptionContext
grok-4.7Grok 4.7 flagship reasoning model500K
ante --provider xai --model grok-4.7

Zai​

ModelDescriptionContext
glm-5.3Latest GLM-5.3 model for coding and agentic tasks1M
glm-5.3-flashFast, cost-efficient GLM-5.3 multimodal model1M
glm-5.3-flashxHigh-speed GLM 5.3 FlashX with native vision1M
ante --provider zai --model glm-5.3

Open Router​

Open Router ships as three providers sharing one API key, split by wire style: openrouter (OpenAI-compatible chat), openrouter-responses (OpenAI Responses), and openrouter-anthropic (Anthropic Messages).

openrouter:

ModelDescriptionContext
deepseek/deepseek-v4.1-flash-1017DeepSeek V4.1 Flash October 17 coding upgrade with vision1.05M
reflection/beam-1.0-501b-a23bReflection Beam 1.0 for coding and long-horizon agentic work1.05M
google/gemini-4-argonGemini 4 Argon for complex reasoning via OpenRouter1.05M
google/gemini-3.8-flashGemini 3.8 Flash for long-horizon coding and autonomous agents1.05M
x-ai/grok-4.7Grok 4.7 flagship reasoning model via OpenRouter500K
qwen/qwen3.8-max-0902Qwen 3.8 flagship multimodal reasoning model1M
qwen/qwen3.7-plusCost-effective Qwen 3.7 model with vision1M
qwen/qwen3.8-flashQwen 3.8 Flash multimodal reasoning model1M
meta/muse-wonderMuse Wonder for complex agentic reasoning and coding1.05M
meta/muse-spark-openMuse Spark Open for agentic coding workflows1.05M
meta/muse-spark-1.3Muse Spark 1.3 multimodal agentic reasoning model1.05M
tencent/hy3Tencent Hy3 agentic reasoning model262K
xiaomi/mimo-v2.6-proMiMo-V2.6-Pro multimodal agentic model1.05M
xiaomi/mimo-v2.6-flashMiMo-V2.6-Flash multimodal agentic model1.05M
z-ai/glm-5.3GLM 5.3 coding and agentic reasoning model via OpenRouter1.05M
z-ai/glm-5.3-flashFast, cost-efficient GLM 5.3 multimodal model via OpenRouter1.05M
moonshotai/kimi-k3.1-proKimi K3.1 Pro multimodal reasoning for long-horizon agentic work1.05M
moonshotai/kimi-k2.7-codeKimi K2.7 Code reasoning model with vision262K
minimax/minimax-m3.1-flashMiniMax M3.1 Flash multimodal reasoning model1M
qwen/qwen3.8-max-primeHigher-throughput Qwen 3.8 Max with vision1M
qwen/qwen3.8-omni-flashQwen 3.8 Omni Flash multimodal reasoning1M
z-ai/glm-5.3-primeHigher-throughput GLM 5.3; text only1M
z-ai/glm-5.3-flashxHigh-speed GLM 5.3 FlashX with native vision1.05M
meta/muse-spark-1.3-contributorCost-efficient Muse Spark 1.3 contributor model1.05M
nvidia/nemotron-3-ultra-550b-a55bComplex agentic reasoning; text only, medium/high effort202.8K

openrouter-responses serves openai/gpt-6-astra, openai/gpt-6-astra-pro, openai/gpt-6.1-sol, openai/gpt-6.1-sol-pro, openai/gpt-6.1-terra, openai/gpt-6.1-terra-pro, openai/gpt-6-luna, openai/gpt-6-luna-pro, all with 1.05M context. The -pro ids select OpenRouter's pro reasoning route.

openrouter-anthropic serves the Claude family over Anthropic Messages: anthropic/claude-haiku-5.5 (1M context), plus anthropic/claude-sonnet-5.5, anthropic/claude-opus-5.5, and anthropic/claude-fable-5.1 (1M).

Each provider also accepts any model from Open Router's full model list by id, as long as it speaks that provider's wire style.

ante --provider openrouter --model deepseek/deepseek-v4.1-flash-1017
ante --provider openrouter-responses --model openai/gpt-6.1-sol
ante --provider openrouter-anthropic --model anthropic/claude-fable-5.1

DeepSeek​

ModelDescriptionContext
deepseek-flashDeepSeek V4.1 Flash with vision1M
ante --provider deepseek --model deepseek-flash

Set DEEPSEEK_API_KEY, and optionally DEEPSEEK_BASE_URL.

MiniMax​

ModelDescriptionContext
MiniMax-M3.1-FlashMiniMax M3.1 Flash multimodal coding and reasoning model1M
ante --provider minimax --model MiniMax-M3.1-Flash

Set MINIMAX_API_KEY, and optionally MINIMAX_BASE_URL.

Antix​

antix serves these models through Antigma, with an Antix sign-in or an Antix API key:

ModelDescriptionContext
gemini-3.8-flashGemini 3.8 Flash for long-horizon coding and autonomous agents1.05M
gemini-4-argonGemini 4 Argon for complex reasoning and autonomous agents1.05M
grok-4.6Grok 4.6 flagship reasoning model500K
kimi-k3.1-proKimi K3.1 Pro multimodal reasoning for long-horizon agentic work1M
qwen3.8-maxLatest Qwen 3.8 Max1M
qwen3.7-plusLatest Qwen 3.7 Plus1M
claude-haiku-5-5Fastest Claude model for high-volume, latency-sensitive work1M
claude-sonnet-5-5Best combination of speed and intelligence1M
claude-opus-5-5Long-running agentic coding and knowledge work1M
claude-fable-5-1Most capable Claude model1M
gpt-6-astraOpenAI's most capable model for complex agentic work1.05M
gpt-6.1-solGPT-6.1 Sol for complex coding and agentic workflows1.05M
gpt-5.6-terraGPT-5.6 balance of intelligence and cost1.05M
gpt-5.6-lunaGPT-5.6 model for efficient, high-volume workloads1.05M
gpt-5.4-miniFaster, cheaper GPT-5.4 model400K
gpt-5.4-nanoSmallest GPT-5.4 model400K
deepseek-flashDeepSeek V4.1 Flash with native vision1M
deepseek-v4-proComplex agentic work; text only, low/high/max effort1M
glm-5.3Latest GLM-5.3 model for coding and agentic tasks1M
glm-5.3-flashFast GLM-5.3 Flash for coding and agentic tasks1M
glm-5.3-flashxHigh-speed GLM 5.3 FlashX with native vision1M
ante auth login antix          # or: export ANTIX_API_KEY=...
ante --provider antix --model claude-sonnet-5-5

Local​

Run GGUF models locally via the built-in llama.cpp engine — no API key required. The local provider is available while an offline model is ready. For managed models, its settings reflect the active context window, thinking, temperature, and vision capabilities. Unloading the model or stopping the server makes local unavailable. Start or attach a model before using --provider local; the flag by itself does not start the engine. See Offline Mode for setup.

ante --provider local

Custom catalog​

Create ~/.ante/catalog.json to add a provider Ante doesn't ship, patch a built-in one, or tweak a model's defaults. It is merged on top of the built-in presets at startup, so you only specify what you want to add or change. Prefer not to write it by hand? Run /add-provider in the TUI: Ante discovers the endpoint's models, can probe which effort levels each one accepts, and writes the entry for you (restart to load it). The examples below are the common cases; see the schema below for all fields and Credentials for every way to authenticate.

Add a hosted provider​

Most hosted endpoints are OpenAI-compatible. Register one with wire_style: "OpenAiCompatible", point base_url at it, and list the models you want to appear in the picker:

{
  "providers": {
    "together": {
      "display_name": "Together AI",
      "base_url": "https://api.together.xyz/v1",
      "wire_style": "OpenAiCompatible",
      "credential": "env:TOGETHER_API_KEY",
      "preferred_models": [
        {
          "id": "moonshotai/Kimi-K2-Instruct",
          "description": "Kimi K2 on Together",
          "max_tokens": 16384,
          "context_limit": 128000,
          "effort": "medium"
        }
      ]
    }
  }
}
export TOGETHER_API_KEY="..."
ante --provider together --model moonshotai/Kimi-K2-Instruct

To keep the key out of your shell profile instead, leave credential out and store the key once with ante auth add together. A new provider with no credential reads the key stored under its own name.

Declare the effort levels a model accepts​

The effort slider's ladder is built in per provider and model family, so a model on a custom endpoint may get a ladder that doesn't match what the endpoint really accepts. Declare the true set with supported_efforts — the slider then shows exactly those levels, and OpenAI-compatible providers send the selected level as the same-named reasoning_effort:

"preferred_models": [
  {
    "id": "kimi-k3",
    "effort": "high",
    "supported_efforts": ["low", "medium", "high"]
  }
]

An empty list ("supported_efforts": []) declares that the model takes no effort setting at all. There is no API that reports supported levels, so when in doubt let /add-provider probe the endpoint for you.

Add a local provider with no auth​

Set credential to null for a provider that needs no key, and leave preferred_models off when the provider has no stable picker/default model list — handy for a local server like Ollama where the available models change as you pull them. You can still pass any model id explicitly with --provider and --model:

{
  "providers": {
    "ollama": {
      "display_name": "Ollama",
      "base_url": "http://localhost:11434/v1",
      "wire_style": "OpenAiCompatible",
      "credential": null
    }
  }
}
ante --provider ollama --model qwen2.5-coder:7b

Patch a built-in provider​

When the key matches a built-in provider, only the fields you set are changed. "credential": null stops the provider sending a credential, which suits a local proxy:

{
  "providers": {
    "openai": {
      "base_url": "http://localhost:8080/v1",
      "credential": null
    }
  }
}

Send a session header​

For a gateway that groups requests by conversation, put ${session_id} in a headers value or an extra_body string. This example patches the built-in OpenAI provider; use your gateway provider's key when configuring one:

{
  "providers": {
    "openai": {
      "headers": { "X-Session-ID": "${session_id}" },
      "extra_body": { "prompt_cache_key": "ante-${session_id}" }
    }
  }
}

Ante fills in the conversation's ID for each session. Resuming keeps that ID, while a fork uses its own new ID. Subagent requests carry the parent's ID so the gateway can group delegated work with the parent. See Templates for environment variables in the same places.

Send extra request parameters​

Gateways and proxies often require a parameter Ante doesn't model. Put it in extra_body and it is merged into every chat and streaming request body for that provider:

{
  "providers": {
    "my-gateway": {
      "display_name": "My Gateway",
      "base_url": "https://gateway.example.com/v1",
      "wire_style": "OpenAiCompatible",
      "credential": "env:MY_GATEWAY_API_KEY",
      "extra_body": {
        "service_tier": "priority"
      }
    }
  }
}

extra_body can only add fields — keys Ante already generates for that wire style (model, messages, stream, and friends) are dropped at startup with a notice, and the provider still loads. See Extra request fields for the full reserved list.

Override model defaults​

Patch a model on the provider that lists it. A preferred_models entry whose id matches a built-in model changes only the fields you set; everything else is left alone:

{
  "providers": {
    "anthropic": {
      "preferred_models": [
        { "id": "claude-opus-5-5", "effort": "max" },
        { "id": "claude-sonnet-5-5", "effort": "high", "max_tokens": 64000 }
      ]
    },
    "openai": {
      "preferred_models": [{ "id": "gpt-6.1-sol", "temperature": 0.2 }]
    }
  }
}

A model served by several providers is patched on each one you use.

Third-party providers​

Using Open Router​

  1. Sign up at openrouter.ai and generate an API key.
  2. Set your API key: 
    export OPENROUTER_API_KEY="sk-or-..."
  3. Use any model from Open Router's model list: 
    ante --provider openrouter --model deepseek/deepseek-v4.1-flash-1017

OpenAI-compatible providers​

Many LLM providers expose an OpenAI-compatible API (e.g., Together AI, Fireworks, Groq Cloud, Perplexity). For a one-off you can reuse the built-in openai-compatible provider via env vars (no catalog edit needed):

  1. Set the base URL — the per-provider variable takes precedence over MODEL_BASE_URL: 
    export OPENAI_COMPATIBLE_BASE_URL="https://api.together.xyz/v1"
  2. Set your API key: 
    export OPENAI_COMPATIBLE_API_KEY="your-provider-api-key"
  3. Run with the OpenAI Compatible provider: 
    ante --provider openai-compatible --model meta-llama/Llama-3-70b-chat-hf

For something you'll use repeatedly, add a named provider to your custom catalog instead so it shows up in the picker.

catalog.json schema​

~/.ante/catalog.json is merged on top of the built-in presets at startup. It has three optional top-level keys, each a map keyed by name:

{
  "providers":      { /* add or patch providers */ },
  "oauth_profiles": { /* OAuth sign-ins; see Credentials */ },
  "helpers":        { /* credential commands; see Credentials */ }
}

A providers entry whose key matches a built-in (e.g. openai) patches that preset field by field; a new key adds a provider. The map key is the value you pass to --provider. An id (or legacy name) field inside an entry is ignored.

note

~/.ante can be relocated with the ANTE_HOME environment variable; the catalog is always $ANTE_HOME/catalog.json.

Provider fields​

FieldRequiredDescription
display_nameNew providers: optionalFriendly name shown in the TUI. New providers default to the provider map key when omitted.
base_urlNew providers: ✅API base URL.
wire_styleNew providers: ✅API dialect Ante speaks — AnthropicMessage, OpenAiCompatible, OpenAiResponse, or Gemini.
credential—The credential to send: a reference such as env:MY_KEY, a list of them, or null for none (see Credentials). A new provider that omits it reads secret:<its key>.
credential_header—The header the credential goes in, sent as is. Omitted, it is sent as Authorization: Bearer <credential>.
headers—Extra headers sent with every request, as a string→string map. Values take templates. null on a key removes a built-in's header. The credential never goes here.
extra_body—Provider-specific JSON fields merged into every chat and streaming request body (see Extra request fields). String values take templates.
thinking_display—Readable reasoning output: off, concise, or detailed, independent of reasoning effort (see Thinking display).
max_request_images—Non-negative integer limiting images per request across all models on this provider. Keeps the newest images and replaces older ones with text markers; 0 omits all images, null clears the cap. See Request image limits. Available since v0.3.2.
supports_web_search—Whether the provider exposes a native web-search affordance. When true, the WebSearch tool is added to sessions on this provider automatically; when false (the default), WebSearch is not offered.
preferred_models—Models shown for this provider in the picker and used as provider defaults (see Model fields). For built-in provider overlays, matching model ids are patched and new ids are appended; omitted leaves the preset list unchanged.
stream_idle_timeout_secs—Timeout in seconds; defaults to 300. Opening a stream uses one shared budget for response headers, error bodies, OAuth refresh, transport retries and backoff, and WebSocket-to-HTTP fallback. Buffered HTTP calls also read their body within that budget. Once streaming, the same duration limits consecutive transport silence; every read resets it, including keepalives, lifecycle events, and partial tool arguments. All model-generation calls stream, including compaction, goal judging, and ambient hints. Raise it for slow local or proxied endpoints; lower it to detect stalls sooner.
{
  "providers": {
    "my-provider": {
      "display_name": "My Provider",
      "base_url": "https://api.example.com/v1",
      "wire_style": "OpenAiCompatible",
      "credential": "env:MY_PROVIDER_API_KEY",
      "headers": { "X-Org": "my-team" },
      "preferred_models": [
        {
          "id": "my-model",
          "description": "My fine-tuned model",
          "max_tokens": 32000,
          "context_limit": 200000,
          "effort": "medium",
          "supported_efforts": ["low", "medium", "high"]
        }
      ]
    }
  }
}

For built-in providers, include only the fields you want to change. A credential you set replaces the preset's list whole. To repoint Anthropic at a local proxy that takes no key and drop its built-in beta header:

{
  "providers": {
    "anthropic": {
      "base_url": "http://localhost:8080/v1",
      "credential": null,
      "headers": { "anthropic-beta": null }
    }
  }
}

Thinking display​

thinking_display controls readable reasoning output independently of effort. Accepted values are off, concise, and detailed. Built-in hosted-provider presets default to detailed; omitting the field in an overlay keeps that preset, while null clears it and leaves display behavior to the endpoint. A new custom provider sends no display parameter until you set one.

{
  "providers": {
    "openai": { "thinking_display": "concise" },
    "anthropic": { "thinking_display": "off" }
  }
}

The setting never changes reasoning effort or continuation state. OpenAI Responses maps the three modes to no summary, concise summary, or detailed summary. Anthropic maps off to omitted reasoning and both readable modes to its summarized form; Gemini enables thought summaries for concise and detailed. Generic OpenAI-compatible Chat Completions has no standard display control and ignores the field; provider-specific controls can still go in extra_body.

Request image limits​

Use max_request_images when an endpoint limits how many images it accepts in one request. The cap applies to all models on that provider and counts images across the entire request, including user messages and tool results. Document attachments, such as PDFs, do not count.

{
  "providers": {
    "openrouter": { "max_request_images": 8 }
  }
}

Ante retains the newest images in request order and replaces older ones with text explaining that they were omitted to fit the provider's image limit. It applies this just before sending the request on all four wire styles; the saved conversation keeps its images. Set 0 to send no images. Built-in presets are uncapped; omitting the field preserves the provider's existing setting, and null clears it. Restart Ante after editing the catalog.

Once the cap is reached, each new image can replace an image in an earlier message in the outgoing request. That changes the prompt prefix and can reduce cache reuse from that point onward.

Extra request fields​

Some gateways and proxies require parameters Ante doesn't model — a service tier, a routing hint, a vendor-specific beta block. extra_body is a JSON object merged into the top level of every chat and streaming request body Ante sends to that provider:

{
  "providers": {
    "my-gateway": {
      "base_url": "https://gateway.example.com/v1",
      "wire_style": "OpenAiCompatible",
      "credential": "env:MY_GATEWAY_API_KEY",
      "extra_body": {
        "service_tier": "priority",
        "routing": { "region": "us-east" }
      }
    }
  }
}

Values are passed through verbatim, so any JSON shape works. On a built-in provider overlay, extra_body merges key by key into the preset's — matching keys are replaced, others are left alone.

extra_body can only add fields, never override the ones Ante generates for the selected wire_style:

wire_styleReserved keys
AnthropicMessagemodel, max_tokens, messages, system, temperature, tools, stream, thinking, stop_sequences, output_config, cache_control
OpenAiCompatiblemodel, messages, reasoning_effort, max_tokens, stream, stream_options, temperature, top_p, top_k, stop, tools, tool_choice, thinking, enable_thinking, thinking_budget, enable_search, search_options
OpenAiResponsemodel, instructions, input, tools, tool_choice, parallel_tool_calls, max_output_tokens, temperature, reasoning, stream, include, store
Geminicontents, systemInstruction, generationConfig, tools, toolConfig

A reserved key is dropped at catalog load and named in the startup notice; the rest of the provider still loads. To change one of these, use the model fields or the environment overrides instead:

Skipped 1 entry in ~/.ante/catalog.json:
  - providers.my-gateway.extra_body: ignoring Ante-owned request field(s): model

Credentials​

A provider's credential says which credential it sends. It is a reference, a list of references, or null:

{
  "providers": {
    "corp":       { "base_url": "https://llm.corp/v1", "wire_style": "OpenAiCompatible",
                    "credential": ["env:CORP_API_KEY", "secret:corp"] },
    "keyed":      { "base_url": "https://api.keyed.dev/v1", "wire_style": "OpenAiCompatible",
                    "credential": "env:KEYED_API_KEY", "credential_header": "x-api-key" },
    "local-proxy": { "base_url": "http://127.0.0.1:4000/v1", "wire_style": "OpenAiCompatible",
                     "credential": null }
  }
}
ReferenceReads
env:NAMEThe environment variable NAME.
secret:NAMEA key stored with ante auth add NAME (or added in /providers).
oauth:PROFILEA sign-in made with ante auth login PROFILE. PROFILE is anthropic, openai, antix, or one of your oauth_profiles.
helper:NAMEThe output of a command in helpers.
  • A list is tried in order, and the first reference that has a value is sent. In /providers you can pick another one for the session.
  • Omitted on a new provider, credential reads secret:<provider key>, so ante auth add <provider key> is all the setup it needs.
  • null sends no credential.
  • A plain key is refused. "credential": "sk-..." is an error, so a key never sits in catalog.json. Store it with ante auth add and refer to it as secret:NAME.
  • Placement: the credential goes out as Authorization: Bearer <credential>. Set credential_header to send it as is in another header, such as x-api-key.

A provider is ready when one of its references has a value. Providers that aren't ready are skipped during auto-detection; using one fails with the fix, for example "Set environment variable CORP_API_KEY or run ante auth add corp".

Second accounts​

Add /label to sign in to a second account on the same profile, or to store a second key:

ante auth login anthropic/work
ante auth add corp/staging

A reference without a label, such as oauth:anthropic, can use any of them. A labeled one, such as oauth:anthropic/work, uses only that one.

Helpers​

A helper is a command that prints a credential: a token from a vault, a cloud CLI, or a rotating key. Define it under helpers and reference it as helper:NAME:

{
  "helpers": {
    "corp": { "command": ["corp-token", "--audience", "llm"], "ttl_secs": 3000 }
  },
  "providers": {
    "corp": { "base_url": "https://llm.corp/v1", "wire_style": "OpenAiCompatible",
              "credential": "helper:corp" }
  }
}

command runs as written, with no shell, and must finish within 15 seconds. The first line of its output is the credential. Ante reuses it for ttl_secs seconds (at most a year), and runs the command again when that time is up or when the server rejects the credential. If the command fails, the request fails with the helper's name; Ante never falls back to another credential. See Use a command for tokens for worked examples.

OAuth profiles​

An OAuth profile is the recipe for a sign-in. The built-in ones are anthropic, openai, and antix. Add your own under oauth_profiles to sign in to another service, with no code change:

{
  "oauth_profiles": {
    "corp": {
      "client_id": "ante",
      "redirect_uri": "http://localhost:1455/callback",
      "authorize_url": "https://sso.corp/authorize",
      "token_url": "https://sso.corp/token",
      "scopes": ["openid", "offline_access"],
      "account_claim": ["email"]
    }
  },
  "providers": {
    "corp": { "base_url": "https://llm.corp/v1", "wire_style": "OpenAiCompatible",
              "credential": "oauth:corp" }
  }
}

Then run ante auth login corp. client_id, redirect_uri, authorize_url, and token_url are required; redirect_uri must be on http://localhost or http://127.0.0.1. Optional fields include scopes, resource, authorize_params, token_request_encoding (json or form), and account_claim (the JWT claim shown as the account in ante auth list). An entry named like a built-in replaces it whole. An oauth: reference to a profile that doesn't exist is an error. Add an OAuth sign-in walks through a full setup.

Templates​

String values in a provider's headers and extra_body, and in an oauth_profiles entry, can use:

TemplateBecomes
${NAME}The environment variable NAME.
${NAME:-default}NAME, or default when it is not set.
${session_id}The ID of the session making the request, in headers and extra_body only (see Send a session header).

Environment variables are read when the catalog loads. A ${NAME} with no value and no default refuses the whole entry, naming the variable. Templates never carry a credential; use credential for that.

Model fields​

A model is described inside a provider's preferred_models. On a built-in provider, an entry whose id matches an existing model patches it, and a new id is added. Every field except id is optional:

FieldDescription
idModel id (name is accepted as a legacy alias).
display_nameFriendly name.
descriptionShort description shown in the model picker.
temperatureSampling temperature. On AnthropicMessage providers, must be 1 while thinking is active; Claude Haiku 5.5 requires 1 regardless of thinking settings. Other values fail before the request is sent.
top_pNucleus sampling cutoff.
top_kTop-k sampling cutoff.
max_tokensMaximum output tokens per turn. On AnthropicMessage providers that take an explicit thinking budget, it must exceed 1024 — the API's minimum budget — when an effort level is set.
stop_sequencesList of strings that end generation.
context_limitContext window size, in tokens.
effortDefault effort level — min, low, medium, high, xhigh, or max. Omit for models with no reasoning knob (Ante then sends no effort parameter and hides the effort slider).
supported_effortsThe effort levels this model accepts on this provider, ascending (same values as effort). Replaces the built-in ladder: the effort slider shows exactly these levels, and OpenAI-compatible providers send the selected level as the same-named reasoning_effort (min is sent as minimal). An empty list declares that the model takes no effort setting. Omit to keep the built-in ladder.
weight_classSize/cost tier — Feather, Middle, or Heavy. Drives automatic default and auxiliary model selection (see Weight classes).
support_visionWhether the model accepts image input. Built-in models declare this explicitly; custom models default to true when unspecified, and an overlay that omits it keeps the preset value. Set false for a text-only endpoint. Images are filtered out before sending to non-vision models without altering saved history; reading an image returns its metadata instead of pixels.

Weight classes​

Every built-in model carries a weight_class — Feather (small/fast/cheap), Middle, or Heavy (largest/most capable). Ante uses it to pick models without you naming one:

  • Default model — selecting a provider with no explicit model resolves to its heaviest model.
  • Ambient UI calls — cosmetic thinking phrases and next-prompt suggestions use the provider's lightest model when it is classified as Feather or Middle. WebFetch returns page content directly to the active session model and does not use this path.

Models with no weight_class set fall back to catalog order. Set weight_class on a custom model to steer these choices.

How a model and provider are chosen​

Explicit --provider and --model flags override the provider and model values in ~/.ante/settings.json. When neither source specifies a choice, Ante uses the auto-detection rules below.

When Ante resolves a model id it layers two sources, last wins:

  1. Provider model spec — the selected provider's preferred_models entry, with your patches, if it lists that id. Otherwise, the first matching entry in catalog order. An unknown id falls back to a bare default spec.
  2. Environment overrides — the process env vars below win over everything.

Providers are matched to models too. If you pass only --model, Ante picks an authenticated provider whose preferred_models list contains that id, falling back to an authenticated provider with no preferred_models, then to the default provider.

A provider you name with --provider or saved in settings is kept even before it is set up: Ante starts on it and says it needs setup in /providers. If you pass both --provider and --model, Ante uses that provider's model spec before applying environment overrides, falling back to a global lookup only when the provider does not list the id. Unknown ids are passed through as bare model specs.

When neither CLI flags nor settings name a model or provider, Ante auto-detects: it uses the first authenticated provider in catalog order (Antix comes first) and that provider's heaviest-weight model (see Weight classes). If nothing is authenticated, it starts on Antix, ready to set up.

Environment overrides​

These process env vars override catalog values for the session without editing the file:

VariableOverrides
MODEL_BASE_URLBase URL for all providers (a per-provider var like ANTHROPIC_BASE_URL takes precedence).
MODEL_TEMPERATUREtemperature
MODEL_TOP_Ptop_p
MODEL_MAX_TOKENSmax_tokens
MODEL_CONTEXT_LIMITcontext_limit

Effort has no env override — set it per run with the --effort CLI flag or per model via the effort field.

Several presets also honor a dedicated base-URL env var that takes precedence over MODEL_BASE_URL: ANTHROPIC_BASE_URL, OPENAI_BASE_URL, OPENAI_COMPATIBLE_BASE_URL, OPENROUTER_BASE_URL, DEEPSEEK_BASE_URL.

Error handling​

A bad entry doesn't sink the whole file. Ante parses catalog.json leniently: any provider, profile, or helper entry that fails to load is skipped, and the rest still load. A setting written in a shape an earlier version used is skipped with a message naming its replacement (see Upgrading to v0.3). Skipped entries are reported at startup and by ante doctor, e.g.:

Skipped 1 entry in ~/.ante/catalog.json:
  - providers.my-provider: missing field `base_url`

Only a file that isn't a JSON object at all is rejected outright. A missing catalog.json is fine — Ante just uses the built-in presets.