Providers
Caudra talks to LLM providers over their HTTP APIs. Model jobs decide which configured or discovered model serves each kind of work.
Model jobs
Section titled “Model jobs”Caudra routes work through eleven jobs: Chat, Plan, Subagent, Compact, Title, Goal, Extract, Memory, Autopilot, Fast, and Best. A global binding can pin a job to an exact provider/model-id or make it follow Chat, Plan, Fast, or Best. Explicit bindings report an error when their model is unavailable or disallowed.
/model opens a Jobs overview and the model list. Selecting a model on this page changes Chat. Selecting the Chat row jumps to its current model. Select another job to open its assignment page, press Esc to return to the overview, and use uppercase R to clear the open job's binding. /goal model opens Goal directly. Jobs are opened from the overview rather than cycled with Tab.
Press Ctrl+F on a model to mark it as a favorite, and again to unmark it. The list shows your favorites first, newest first, then the last 10 models you switched to under Recent. With favorites, /model opens on the current model's favorite row, or on the first favorite, instead of on the Chat job. Each model also stays in its provider's section, where a ★ marks a favorite and a ↺ a recent model. /model next or Ctrl+X c switches Chat to the favorite after the current model, and to the first favorite when the current model is not one. Favorites are saved globally, like bindings, and a favorite that allowed_models or excluded_models rules out is not shown. A task model name such as sonnet runs on the favorite it matches, and the main agent is told your favorites. See Models and reasoning.
The last row of the Jobs section, Decisions, names the active decision endpoint, or off. Select it to switch endpoints, turn decisions off, or add an endpoint through /login. An endpoint whose table does not validate stays listed with its error. /decisions model opens that page directly, and /decisions next or Ctrl+X d switches to the next valid endpoint in name order. Decision endpoints never appear under Favorites or Recent.
Bindings are saved globally in the model.purposes row of Caudra's SQLite state database and apply across sessions. Unbound jobs use these rules:
| Job | Default when unbound |
|---|---|
| Chat | The anchor model |
| Plan | The anchor model |
| Subagent | The model currently running its parent |
| Compact | The model currently running the caller |
| Title | Fast |
| Goal | Fast |
| Extract | Fast |
| Memory | The model currently running the caller |
| Autopilot | Best |
| Fast | Provider fast config, curated preferred small model, cheapest priced model, fewest-parameter model, then the anchor |
| Best | Provider best config, curated flagship, then the anchor |
The anchor is the selected Chat model when a main turn starts. A Plan binding can select a distinct model, which Caudra uses for main turns sent in Plan mode. An explicit global Subagent binding overrides parent inheritance. A prompt profile's subagent_model overrides the global Subagent binding for tasks using that profile. See System Prompt Profiles. A model set on one task call overrides both. See Models and reasoning.
See Sessions for Title, Completion goals for Goal, Requirements for Extract, Memory for Memory, and Autopilot for Autopilot.
Supply metadata
Section titled “Supply metadata”Provider catalogs record whether a model is small and whether it is the preferred model in its size lane. The tables below and caudra models render those facts with three markers:
| Marker | Meaning |
|---|---|
| Small | A small alternative |
| Fast | The preferred small model |
| Best | The provider's flagship |
A known non-small alternative and a model with no supply facts both have no marker. Markers describe provider supply. They are not capability tiers, and price or list order never creates one. Fast may still use price or parameter count as its final provider fallback without adding a marker.
Aggregators such as OpenRouter borrow supply facts from the upstream vendor entry in a vendor-prefixed model id.
Provider purposes entries in providers.toml define the same supply facts. fast entries are small and best entries are non-small. The first entry in each list is preferred, so it receives the Fast or Best marker. Later fast entries receive Small, while later best entries remain unmarked. Entries match by prefix, so an endpoint serving a family of fine-tunes needs one line rather than one per variant:
[my-server.purposes]fast = "qwen3.8-27b" # covers qwen3.8-27b, qwen3.8-27b-canary, qwen3.8-27b-math7, ...The first entry also names the model that wins automatic resolution, so it has to name a model the endpoint actually serves. A prefix that matches nothing live would send requests to an id that does not exist.
Model list
Section titled “Model list”Model prices, limits, defaults, and availability come from a signed model list. Every Caudra binary bundles a copy, so the list works offline, and the model tables on this page show that copy. At startup Caudra also reads the signed cache in models/v1/ under its cache directory. The newer updated_at wins as a whole file. The bundled copy wins a tie. Cached files do not expire.
The list also carries a reviewed import of the models.dev catalog. It describes models that have no curated entry, and the providers Caudra reaches only through it, such as NVIDIA and Groq. Caudra sends Groq requests to https://api.groq.com/openai/v1 with GROQ_API_KEY, whatever the model list says. Caudra does not contact models.dev itself.
Long-running sessions check https://models.caudra.ai/v1/models.json in the background when the last check is more than 24 hours old, and check daily after that. A missing or invalid cache, or a check timestamp in the future, triggers a new check. Startup does not wait for a request. --print uses the cache without starting a refresh. A running session applies new model settings at its next turn, not during a response. If its model no longer resolves, it keeps the previous settings and logs a warning.
caudra models refresh checks now, even with automatic refresh disabled. It prints the previous and current publication times and whether the file changed. If another process is refreshing, it reports that and exits with an error. A failed check keeps the current list. A verified update takes effect even if saving the cache fails.
In the TUI, /model refresh runs the same check without blocking the session and shows the result in the status bar.
[models]refresh = trueurl = "https://models.caudra.ai/v1/models.json"Set refresh = false or CAUDRA_MODELS_REFRESH=0 to stop automatic requests. CAUDRA_MODELS_REFRESH=1 enables them unless the project disables refresh. The environment override also accepts false or true, no or yes, and off or on, without regard to case. Invalid values warn and leave the configured setting unchanged. The override comes from the process or global .env, never a project .env. Cached files still load when refresh is disabled.
url is global-only and can point to a mirror over HTTPS, or HTTP on localhost, 127.0.0.1 or [::1]. A project can only disable refresh. Its URL and attempts to enable refresh are ignored. Caudra fetches the signature from <url>.sig. Changing the URL does not change which signing keys Caudra trusts. Restart after changing these settings.
Downloaded and cached files must pass Ed25519 verification with a public key shipped in Caudra, size checks and format validation. An unknown signing key or incompatible format rejects the whole file. Caudra keeps its bundled endpoint, credential names, and protocol for protected catalog providers. It drops new rows that claim protected endpoints or credentials and logs a warning, without rejecting the rest of the file. Entries that need newer Caudra features stay hidden and cannot be selected. An unsupported built-in provider keeps its previous manifest.
An interrupted cache write leaves the previous list in use.
The list is maintained in github.com/caudra/models. To report a wrong price or limit, or a missing model, open an issue or a pull request there.
Auth Reloading
Section titled “Auth Reloading”Caudra re-reads auth from storage and environment variables each time a new agent spawns (/new, retry, session load). If you run caudra auth login in another terminal or change an env var, the next session picks it up without a restart.
A provider can have several accounts, such as two subscriptions and an API key, and an env var with keys separated by commas (ANTHROPIC_API_KEY=sk-1,sk-2) gives one account per key. A login, a logout, or an account choice made in another process reaches a running conversation at its next cold point. See Accounts for how Caudra chooses between them.
Base URL Overrides
Section titled “Base URL Overrides”Most providers, custom ones included, honor a <SLUG>_BASE_URL env var, where <SLUG> is the slug in capitals with _ for - (anthropic -> ANTHROPIC_BASE_URL, openrouter -> OPENROUTER_BASE_URL). Set it to the origin of a proxy or a compatible endpoint and Caudra appends the API paths itself:
ANTHROPIC_BASE_URL=https://my-proxy.internal caudraIt wins over providers.toml and built-in defaults. ANTHROPIC_BASE_URL and OPENAI_BASE_URL are the same names the official SDKs use, so an existing proxy setup carries over as is. Three exceptions apply. ANTHROPIC_BASE_URL never receives Claude subscription tokens. OPENAI_BASE_URL only redirects the platform API, never the ChatGPT Coding Plan backend. XAI_BASE_URL only redirects the public API-key endpoint, never the OAuth CLI proxy.
You can also set base_url for a built-in provider in ~/.config/caudra/providers.toml. It overrides the built-in default and loses to the env var above:
[openai]base_url = "http://xxxx:1234/v1"The built-in provider still owns the slug, so protocol, api_key_env and discover_models are ignored with a warning. Its model_defaults and models entries only set a model's context_window and max_output_tokens, see Model limits on a built-in provider. Use a custom slug if you need the rest.
Ollama reads OLLAMA_HOST and llama.cpp reads LLAMA_CPP_HOST. Neither reads <SLUG>_BASE_URL. A base_url in providers.toml wins over the host variable, and Caudra appends /v1 to either, so leave it off. Aperture reads APERTURE_HOST, which wins over the file. Copilot asks GitHub for the API endpoint of your account, Copilot Enterprise derives it from the host you signed in with, and both ignore these settings.
Built-in Providers
Section titled “Built-in Providers”Anthropic
Section titled “Anthropic”- Env var:
ANTHROPIC_API_KEY(also supports subscription OAuth viacaudra auth login anthropic) - API:
https://api.anthropic.com/v1/messages - Features: Prompt caching, thinking mode (adaptive/budgeted), advanced tool use
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Fast | claude-haiku-5-5 (default) | $0.10 / $0.50 | 372K ctx / 128K out |
| Small | claude-haiku-4-5 | $1.00 / $5.00 | 200K ctx / 64K out |
| claude-sonnet-4-5 (retires 2026-11-30) | $3.00 / $15.00 | 200K ctx / 64K out | |
| claude-sonnet-4-6 | $3.00 / $15.00 | 372K ctx / 128K out | |
| claude-sonnet-5-5 | $2.00 / $10.00 | 372K ctx / 128K out | |
| claude-sonnet-5 | $2.00 / $10.00 | 372K ctx / 128K out | |
| claude-opus-4-5 | $5.00 / $25.00 | 200K ctx / 64K out | |
| claude-opus-4-6 | $5.00 / $25.00 | 372K ctx / 128K out | |
| claude-opus-4-7 | $5.00 / $25.00 | 372K ctx / 128K out | |
| claude-opus-4-8 | $5.00 / $25.00 | 372K ctx / 128K out | |
| Best | claude-opus-5-5 (default) | $4.00 / $20.00 | 372K ctx / 128K out |
| claude-opus-5 | $5.00 / $25.00 | 372K ctx / 128K out | |
| claude-fable-5-1 | $10.00 / $50.00 | 372K ctx / 128K out | |
| claude-fable-5 | $10.00 / $50.00 | 372K ctx / 128K out |
Routing defaults: claude-haiku-5-5 (Fast), claude-opus-5-5 (Best)
Run caudra auth login anthropic to sign in to a Claude subscription through browser OAuth. Caudra stores the tokens in its state directory, refreshes them automatically, and shows subscription limits through /usage. Subscription requests always go to api.anthropic.com, even when ANTHROPIC_BASE_URL is set.
This experimental flow uses Claude Code's public client registration. Anthropic limits Pro and Max subscription tokens to official clients in its terms. The flow may stop working when Anthropic changes its OAuth or request protocol.
Recent Claude models accept up to 1M tokens. Caudra runs them at a 372k working window, which keeps cost and latency bounded. That window is an input budget: the model's output allowance sits on top of it rather than inside it, so Caudra holds back less of it before compaction. Add -1m to a model id, like claude-sonnet-4-6-1m, to open the full 1M window instead. Set context_window in providers.toml to pick any other size, see Model limits on a built-in provider. claude-haiku-5-5 bills a whole request at five times its listed rates once the prompt passes 100k tokens, cached tokens included, and Caudra counts its cost the same way.
Amazon Bedrock
Section titled “Amazon Bedrock”If you already use Claude through AWS Bedrock, you can point Caudra at it instead of the direct Anthropic API. Set CLAUDE_CODE_USE_BEDROCK=1 and Caudra will route all Anthropic requests through Bedrock. The same models, the same features, just a different door.
You will need AWS_REGION and one of the following for auth:
| Method | Env vars |
|---|---|
| IAM credentials | AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (and optionally AWS_SESSION_TOKEN) |
| Credentials file | AWS_PROFILE (defaults to default), reads ~/.aws/credentials |
| Bearer token | AWS_BEARER_TOKEN_BEDROCK |
| Gateway proxy | CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 + ANTHROPIC_BEDROCK_BASE_URL (skips signing, useful behind a proxy that handles auth) |
You can override the model with ANTHROPIC_MODEL and the endpoint with ANTHROPIC_BEDROCK_BASE_URL. These env var names match Claude Code, so if you were already using Bedrock there, the same setup works here.
OpenAI
Section titled “OpenAI”- Env var:
OPENAI_API_KEY(also supports OAuth device flow) - API:
https://api.openai.com/v1
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Fast | gpt-6-luna (gpt-6 default) | $0.10 / $0.50 | 372K ctx / 128K out |
| Fast | gpt-5.6-luna (gpt-5.6 default) | $0.20 / $1.20 | 372K ctx / 128K out |
| Small | gpt-5.4-nano (retires 2027-04-01) | $0.20 / $1.25 | 400K ctx / 128K out |
| Small | gpt-5.4-mini | $0.75 / $4.50 | 400K ctx / 128K out |
| Best | gpt-6-astra (gpt-6 default) | $10.00 / $50.00 | 372K ctx / 128K out |
| gpt-6.1-sol | $2.00 / $10.00 | 372K ctx / 128K out | |
| gpt-6.1-terra | $1.00 / $5.00 | 372K ctx / 128K out | |
| gpt-6-sol | $2.00 / $10.00 | 372K ctx / 128K out | |
| gpt-5.6-terra | $2.00 / $12.00 | 372K ctx / 128K out | |
| Best | gpt-5.6-sol, gpt-5.6 (gpt-5.6 default) | $4.00 / $20.00 | 372K ctx / 128K out |
| gpt-4.1-mini | $0.40 / $1.60 | 1047K ctx / 32K out | |
| gpt-4.1 | $2.00 / $8.00 | 1047K ctx / 32K out | |
| gpt-5.5-pro | $30.00 / $180.00 | 1050K ctx / 128K out | |
| gpt-5.5 | $5.00 / $30.00 | 1050K ctx / 128K out | |
| gpt-5.4-pro | $30.00 / $180.00 | 1050K ctx / 128K out | |
| gpt-5.4 | $2.50 / $15.00 | 1050K ctx / 128K out | |
| o3-pro (retires 2026-12-11) | $20.00 / $80.00 | 200K ctx / 100K out | |
| o3 (retires 2026-12-11) | $2.00 / $8.00 | 200K ctx / 100K out | |
| gpt-5.3-codex (retires 2027-04-01) | $1.75 / $14.00 | 400K ctx / 128K out | |
| gpt-5.2-pro | $21.00 / $168.00 | 400K ctx / 128K out | |
| gpt-5.2 | $1.75 / $14.00 | 400K ctx / 128K out |
Routing defaults: gpt-6-luna (Fast), gpt-6-astra (Best)
A lane answers inside the release line you are on. On gpt-6 that is gpt-6-luna (Fast) and gpt-6-astra (Best). On gpt-5.6 that is gpt-5.6-luna (Fast) and gpt-5.6-sol (Best).
- Env var:
GEMINI_API_KEY - API:
https://generativelanguage.googleapis.com/v1beta - Features: Native Gemini API with thinking support
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Fast | gemini-3.5-flash-lite (default) | $0.30 / $2.50 | 1048K ctx / 65K out |
| Best | gemini-4-argon (default) | $2.00 / $10.00, then $4.00 / $20.00 from 2026-12-01 | 1048K ctx / 65K out |
| gemini-3.8-flash | $0.75 / $3.75, then $1.50 / $7.50 from 2027-01-01 | 1048K ctx / 65K out | |
| gemini-3.6-flash | $0.75 / $3.75, then $1.50 / $7.50 from 2027-01-01 | 1048K ctx / 65K out |
Routing defaults: gemini-3.5-flash-lite (Fast), gemini-4-argon (Best)
Create a GEMINI_API_KEY in Google AI Studio. gemini-4-argon needs a key on a project with billing enabled, because the free tier does not serve it. On the free tier, pick google/gemini-3.8-flash instead. Where a price above names a date, Caudra bills the first price until that day and the second from 00:00 UTC on it, so an introductory price ends on time without an update. Gemini 4 and Gemini 3 models always think, so thinking off runs at the lowest level the model accepts.
A Google AI Pro or Ultra plan covers AI Studio in the browser. Google bills API calls separately, so the plan does not pay for Caudra's requests. Caudra offers no Google sign-in, because Google's terms forbid third-party tools from using the sign-in of Gemini CLI or Antigravity, and Google may suspend accounts that do. On Copilot Pro+, Max, Business or Enterprise, copilot/gemini-4-argon runs Argon on your Copilot plan.
Copilot
Section titled “Copilot”- Env var:
GH_COPILOT_TOKENorCOPILOT_GITHUB_TOKEN(or runcaudra auth login copilotto sign in with GitHub) - API:
https://api.githubcopilot.com (or GraphQL-discovered Copilot API endpoint) - Features: Native Copilot Chat HTTP API with model endpoint discovery
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Small | gpt-5.4-nano | $0.20 / $1.25 | 200K ctx / 100K out |
| Small | claude-haiku-4.5 | $1.00 / $5.00 | 200K ctx / 64K out |
| Small | claude-haiku-5.5 | $0.10 / $0.50 | 200K ctx / 100K out |
| Small | mai-code-1.1-flash | $0.20 / $1.20 | 200K ctx / 100K out |
| Small | gpt-6-luna | $0.10 / $0.50 | 200K ctx / 100K out |
| Fast | gpt-5.6-luna (default) | $0.20 / $1.20 | 200K ctx / 100K out |
| gemini-3.8-flash | $0.75 / $3.75 | 200K ctx / 65K out | |
| claude-sonnet-4.6 | $3.00 / $15.00 | 200K ctx / 64K out | |
| claude-sonnet-5.5 | $2.00 / $10.00 | 200K ctx / 100K out | |
| claude-sonnet-5 | $2.00 / $10.00 | 200K ctx / 100K out | |
| kimi-k3 | $3.00 / $15.00 | 200K ctx / 100K out | |
| gemini-4-argon | $2.00 / $10.00 | 200K ctx / 65K out | |
| gpt-6.1-sol | $2.00 / $10.00 | 200K ctx / 100K out | |
| gpt-6.1-terra | $1.00 / $5.00 | 200K ctx / 100K out | |
| gpt-6-sol | $2.00 / $10.00 | 200K ctx / 100K out | |
| gpt-5.6-sol | $4.00 / $20.00 | 200K ctx / 100K out | |
| gpt-5.6-terra (retires 2026-11-16) | $2.00 / $12.00 | 200K ctx / 100K out | |
| gpt-5.3-codex | $1.75 / $14.00 | 200K ctx / 100K out | |
| Best | claude-opus-5 (default, retires 2026-11-16) | $5.00 / $25.00 | 200K ctx / 64K out |
| Best | claude-opus-5.5 (default) | $4.00 / $20.00 | 200K ctx / 128K out |
| claude-opus-4.8 | $5.00 / $25.00 | 200K ctx / 64K out | |
| claude-opus-4.8-fast, claude-fable-5 | $10.00 / $50.00 | 200K ctx / 100K out | |
| claude-fable-5.1 | $10.00 / $50.00 | 200K ctx / 100K out | |
| gpt-6-astra | $10.00 / $50.00 | 200K ctx / 100K out | |
| grok-4.5 | $2.00 / $6.00 | 200K ctx / 100K out | |
| grok-4.6 | $2.00 / $6.00 | 200K ctx / 100K out | |
| grok-4.7 | $2.00 / $6.00 | 200K ctx / 100K out |
Routing defaults: gpt-5.6-luna (Fast), claude-opus-5 (Best) until 2026-11-16, then claude-opus-5.5 (Best)
Run caudra auth login copilot to sign in with GitHub. Caudra prints a URL and a one-time code, opens the browser when it can, and waits until you approve the code on GitHub. The login uses the same public GitHub OAuth app as OpenCode and asks only for the read:user scope. GitHub issues a token that does not expire, so there is no refresh. When GitHub revokes it, run the login again.
To reuse a token from the gh CLI, the Copilot editor plugin, or the system keyring instead, add --method import. Caudra stores the token in its state directory and labels it token in caudra auth status. GH_COPILOT_TOKEN or COPILOT_GITHUB_TOKEN wins over the saved token.
Copilot lists a prompt limit for each model beside its total window, and refuses a longer prompt even when the total has room. Caudra uses that prompt limit as the model's window, with the output allowance on top of it, so a session compacts before Copilot refuses it.
Copilot Enterprise
Section titled “Copilot Enterprise”- Env var:
GH_COPILOT_ENTERPRISE_TOKENwithGH_COPILOT_ENTERPRISE_HOST(or runcaudra auth login copilot-enterpriseto sign in with GitHub) - API:
https://copilot-api.<enterprise-host> - Features: Native Copilot Chat HTTP API for one GitHub Enterprise host
Copilot Enterprise is a separate provider, so a GitHub Enterprise account and a personal account can stay signed in together. Run caudra auth login copilot-enterprise --hostname company.ghe.com, or leave out --hostname and Caudra asks for it. A name without a dot, such as company, means company.ghe.com. The login runs against that host and saves the token together with the host. --method import reads gh CLI and Copilot plugin tokens for that host only.
Caudra sends requests to https://copilot-api.<host> and never falls back to public GitHub. This follows the endpoint scheme OpenCode uses for GitHub Enterprise Cloud with data residency. Other deployments may not serve Copilot there. For CI, set GH_COPILOT_ENTERPRISE_TOKEN and GH_COPILOT_ENTERPRISE_HOST together. The token variable alone is an error, never a public GitHub token.
The models are the ones Copilot lists above, under copilot-enterprise/, such as copilot-enterprise/gpt-6.1-terra. Your organization's policy decides which of them your account can use.
Ollama
Section titled “Ollama”- Env var:
OLLAMA_HOSTfor local/remote (e.g.http://localhost:11434),OLLAMA_API_KEYfor auth - API:
http://localhost:11434/v1 - Features: Local or remote inference via OLLAMA_HOST, cloud fallback via OLLAMA_API_KEY
This provider talks the OpenAI-compatible /v1 API, so it also works with llama.cpp's server, LocalAI, or anything else that speaks the same protocol. Just point OLLAMA_HOST to the right address (e.g. http://localhost:8080 for llama.cpp).
LlamaCpp
Section titled “LlamaCpp”- Env var:
LLAMA_CPP_API_KEY - API:
http://localhost:8080/v1 - Features: Local or remote inference via LLAMA_CPP_HOST, set optional key via LLAMA_CPP_API_KEY
Connects to any OpenAI-compatible /v1 endpoint. Set LLAMA_CPP_HOST to your server address, such as http://localhost:8080, or run caudra auth login llama-cpp, which offers that address and saves your answer to providers.toml. Without either, Caudra reports that LLAMA_CPP_HOST is not set.
Mistral
Section titled “Mistral”- Env var:
MISTRAL_API_KEY - API:
https://api.mistral.ai/v1
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Small | zai-glm-5-3-flash | $0.15 / $0.50 | 1000K ctx |
| Fast | ministral-14b-latest, ministral-14b-2512 (default) | $0.20 / $0.20 | 262K ctx |
| Best | mistral-medium-latest, mistral-medium-3.5, mistral-medium-3-5, mistral-medium-2604, mistral-medium-3 (default) | $1.50 / $7.50 | 262K ctx |
| mistral-large-4 | $0.68 / $2.09, then $1.36 / $4.18 from 2026-10-20 | 1000K ctx | |
| mistral-large-latest, mistral-large-2512 | $0.50 / $1.50 | 262K ctx | |
| glm-5-3, zai-glm-5-3, zai-glm-5, zai-glm-latest | $1.40 / $4.40 | 1000K ctx | |
| glm-5-2, zai-glm-5-2 (retires 2026-10-31) | $1.40 / $4.40 | 1000K ctx | |
| deepseek-v4-1-flash-1017 | $0.30 / $1.20 | 1000K ctx | |
| mistral-small-latest, mistral-small-2603 | $0.15 / $0.60 | 262K ctx |
Routing defaults: ministral-14b-latest (Fast), mistral-medium-latest (Best)
- Env var:
ZHIPU_API_KEY(shared across both endpoints) - API endpoints:
https://api.z.ai/api/paas/v4https://api.z.ai/api/coding/paas/v4
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Small | glm-5.3-flashx | $0.37 / $1.25 | 1000K ctx / 131K out |
| Small | glm-5.3-flash | $0.15 / $0.50 | 1000K ctx / 131K out |
| Small | glm-4.7-flashx | $0.07 / $0.40 | 200K ctx / 131K out |
| Fast | glm-4.7-flash (default) | $0.00 / $0.00 | 200K ctx / 131K out |
| Small | glm-4.6v-flashx | $0.04 / $0.40 | 128K ctx |
| Small | glm-4.6v-flash | $0.00 / $0.00 | 128K ctx |
| Small | glm-4.5-flash | $0.00 / $0.00 | 131K ctx / 98K out |
| Small | glm-4.5-air | $0.20 / $1.10 | 131K ctx / 98K out |
| Small | glm-4.5-airx | $1.10 / $4.50 | 131K ctx / 98K out |
| Best | glm-5.3 (default) | $1.40 / $4.40 | 1000K ctx / 131K out |
| glm-5.2 | $1.40 / $4.40 | 1000K ctx / 131K out | |
| glm-5.1 | $1.40 / $4.40 | 200K ctx / 131K out | |
| glm-5 | $1.00 / $3.20 | 200K ctx / 131K out | |
| glm-4.7, glm-4.6 | $0.60 / $2.20 | 200K ctx / 131K out | |
| glm-4.6v | $0.30 / $0.90 | 128K ctx | |
| glm-4.5-x | $2.20 / $8.90 | 131K ctx / 98K out | |
| glm-4.5 | $0.60 / $2.20 | 131K ctx / 98K out |
Routing defaults: glm-4.7-flash (Fast), glm-5.3 (Best)
DeepSeek
Section titled “DeepSeek”- Env var:
DEEPSEEK_API_KEY - API:
https://api.deepseek.com - Features: Thinking mode toggle (on/off), open-weight models
- Peak pricing: the prices below are off-peak; each turn is billed as it happens, at 2x during 01:00-04:00, 06:00-10:00 UTC
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| deepseek-flash, deepseek-v4-flash | $0.15 / $0.60 | 1000K ctx / 393K out | |
| Best | deepseek-v4-pro (default) | $0.66 / $1.98 | 1000K ctx / 393K out |
Routing defaults: deepseek-v4-pro (Best)
OpenRouter
Section titled “OpenRouter”- Env var:
OPENROUTER_API_KEY - API:
https://openrouter.ai/api/v1 - Features: 300+ models from all providers, prompt caching, provider routing
OpenRouter aggregates models from many providers behind a single API key. Browse available models at openrouter.ai/models. Use any model ID directly (e.g. openrouter/anthropic/claude-sonnet-4).
Synthetic
Section titled “Synthetic”- Env var:
SYNTHETIC_API_KEY - API:
https://api.synthetic.new/openai/v1 - Features: Reasoning effort support (low/medium/high), open-weight models
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Fast | hf:zai-org/GLM-4.7-Flash (default) | $0.10 / $0.50 | 196K ctx / 65K out |
| Small | hf:zai-org/GLM-5.3-Flash | $0.15 / $0.50 | 524K ctx / 65K out |
| Small | hf:Qwen/Qwen3.8-27B | $0.45 / $2.20 | 262K ctx / 65K out |
| Best | hf:moonshotai/Kimi-K3 (default) | $3.00 / $15.00 | 524K ctx / 65K out |
| hf:zai-org/GLM-5.3 | $1.40 / $4.40 | 524K ctx / 65K out | |
| hf:deepseek-ai/DeepSeek-V4.1-Flash-1017 | $0.60 / $1.20 | 524K ctx / 65K out | |
| hf:deepseek-ai/DeepSeek-V4.1-Flash | $0.60 / $1.20 | 524K ctx / 65K out | |
| hf:nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4 | $0.30 / $1.00 | 262K ctx / 65K out | |
| hf:openai/gpt-oss-120b | $0.10 / $0.10 | 131K ctx / 65K out |
Routing defaults: hf:zai-org/GLM-4.7-Flash (Fast), hf:moonshotai/Kimi-K3 (Best)
TensorX
Section titled “TensorX”- Env var:
TENSORX_API_KEY - API:
https://api.tensorx.ai/v1 - Features: Open-weight models, zero data retention, prompt caching
No hardcoded model catalog. Use any model ID supported by this provider.
Opencode Zen
Section titled “Opencode Zen”- Env var:
OPENCODE_API_KEY - API:
https://opencode.ai/zen/v1 - Features: Models from the bundled catalog, including Opencode Zen
No hardcoded model catalog. Use any model ID supported by this provider.
By default Caudra hides free models from the Opencode catalog. To list free models (they use a public fallback, no API key needed), add this to ~/.config/caudra/providers.toml:
[opencode]enable_free_models = trueThe default is false.
- Env var:
XAI_API_KEY(also supports OAuth viacaudra auth login xai) - API endpoints:
https://api.x.ai/v1https://cli-chat-proxy.grok.com/v1
- Features: OAuth login, account-specific model catalog, Grok reasoning (low/medium/high/xhigh)
| Marker | Models | Pricing (in/out per 1M tokens) | Context |
|---|---|---|---|
| Best | grok-4.7 (default) | $2.00 / $6.00 | 500K ctx / 131K out |
| grok-4.6 | $2.00 / $6.00 | 500K ctx / 131K out | |
| grok-4.5 | $2.00 / $6.00 | 500K ctx / 131K out | |
| grok-4.3 | $1.25 / $2.50 | 1000K ctx / 131K out |
Routing defaults: grok-4.7 (Best)
OAuth uses the same first-party xAI client as the official Grok CLI (caudra auth login xai). Browser login (PKCE) is the desktop default; device code is recommended over SSH or in a container. Tokens refresh automatically. After login, Caudra fetches your account catalog from GET /v1/models-v2 on the Grok CLI proxy and caches it for 15 minutes. XAI_BASE_URL only redirects the public API-key endpoint, never the OAuth proxy.
The Grok CLI proxy only serves clients that declare a recent Grok CLI version, so Caudra sends the version it was tested against. When xAI raises its minimum before you update Caudra, requests fail with HTTP 426 and the error names the version the proxy wants. Set CAUDRA_XAI_CLIENT_VERSION to that version to keep working until you update.
If ~/.grok/auth.json already exists, login offers to reuse it without writing that file.
Aperture
Section titled “Aperture”- Env var:
APERTURE_HOST(e.g.https://your-host.tailnet.ts.net) - API:
Aperture gateway (set APERTURE_HOST) - Features: Tailscale Aperture LLM gateway; set APERTURE_HOST or configure in providers.toml
Aperture discovers models from your gateway. Set APERTURE_HOST to your Tailscale Aperture endpoint (e.g. https://your-host.tailnet.ts.net). No API key needed, Tailscale handles auth.
Opencode Go
Section titled “Opencode Go”- Env var:
OPENCODE_API_KEY - API:
https://opencode.ai/zen/go/v1 - Features: Models from the bundled catalog, including Opencode Go
No hardcoded model catalog. Use any model ID supported by this provider. An API key is required.
Model Identifiers
Section titled “Model Identifiers”Models are referenced as provider/model_id:
anthropic/claude-sonnet-4-6openai/gpt-4.1xai/grok-4.6zai/glm-4.7If the model name is unique across providers, the prefix can be omitted.
providers.toml
Section titled “providers.toml”providers.toml lives in the config directory (~/.config/caudra/providers.toml on Linux/macOS, %APPDATA%\caudra\providers.toml on Windows). It is the file for provider overrides and custom HTTP providers. Two jobs:
- Tweak a built-in (pick a plan, change its base URL, set
enable_free_modelsfor Opencode). - Declare a custom provider that speaks OpenAI, Anthropic, or Google wire format.
# Point a built-in at a proxy. Env vars still win over this file.[anthropic]base_url = "https://my-proxy.internal"
# Full custom provider. Slug becomes the `provider/` prefix in model specs.[my-proxy]display_name = "My Proxy"protocol = "openai" # openai | openai-responses | anthropic | googlebase_url = "https://llm.example.com/v1"api_key_env = "MY_PROXY_API_KEY"default_model = "my-proxy/fast-v1"discover_models = true # also list models via the provider's /models endpoint
[my-proxy.purposes]fast = "fast-v1" # a prefix: also covers fast-v1-turbo, fast-v1-lora, ...best = ["smart-v1", "smart-v0"] # a list when one prefix cannot span them
[[my-proxy.models]]id = "fast-v1"context_window = 128000max_output_tokens = 16384pricing_input = 0.5pricing_output = 1.5
[[my-proxy.models]]id = "smart-v1"context_window = 200000max_output_tokens = 32000supports_thinking = truesupports_vision = falseThe file starts with version = 1. A file without it counts as version 1, and Caudra adds the key when it saves or upgrades the file. A newer version stops Caudra with an error rather than being misread. Because version belongs to the file, a custom provider cannot use it as a name. See Config file versions.
caudra config example providers prints every providers.toml key with its default, all commented out. Reference configs shows the same text.
Provider fields
Section titled “Provider fields”| Field | Type | Default | Env | Description |
|---|---|---|---|---|
display_name | string | the built-in name, or the slug | - | The name pickers and auth status show |
protocol | string | required | - | The wire format: openai, openai-responses, anthropic, or google |
base_url | string | the plan URL, or the built-in URL | <SLUG>_BASE_URL | The API origin. Caudra appends the protocol paths |
plan | string | unset | - | A built-in plan key, which sets the base URL and the default model |
api_key_env | string | <SLUG>_API_KEY | - | The environment variable that holds the API key |
api_key | string | unset | - | An API key, stored as plain text unless you write {env:NAME} or {file:PATH} to read it from your environment or a file. Caudra tries the environment variable and saved credentials first |
default_model | string | unset | - | The model to use after login when none is saved yet, such as my-provider/my-model |
discover_models | bool | false | - | Also list the models the provider's model endpoint reports |
enable_free_models | bool | unset | - | Opencode only. Show the free models of its catalog. Unset counts as false |
overrides | table | unset | - | Aperture only. Overrides for the upstream providers it routes, keyed by upstream id |
model_defaults | table | unset | - | Model keys for every model of the provider |
purposes | table | unset | - | Model id prefixes for the fast and best purposes |
models | table[] | unset | - | The models the provider serves |
switching | table | unset | - | When Auto moves a session to another of the provider's accounts |
accounts | table[] | unset | - | The accounts to sign in with, highest priority first |
A built-in slug keeps its compiled protocol and auth setup, and its models from the model list, so it ignores protocol, api_key_env, discover_models and enable_free_models. Opencode still reads enable_free_models. From model_defaults and models, a built-in reads only context_window and max_output_tokens, see Model limits on a built-in provider.
A [SLUG.purposes] table takes these keys:
| Field | Type | Default | Description |
|---|---|---|---|
fast | string | string[] | unset | Model id prefixes for small, fast models, best first. A prefix covers every id that starts with it, and the first one also names the model that fills the slot, so it has to be a real id |
best | string | string[] | unset | Model id prefixes for flagship models, best first. A prefix cannot also be in fast. A model a job is bound to in the picker wins over both lists |
Model fields
Section titled “Model fields”Each [[SLUG.models]] entry declares one model:
| Field | Type | Default | Description |
|---|---|---|---|
id | string | required | The model id, which makes the spec SLUG/ID |
context_window | integer | discovered, or the protocol default | Tokens of context |
max_output_tokens | integer | discovered, or the protocol default | The most tokens one response may hold |
supports_tool_examples | bool | false | Send tool examples as a structured field. It is off unless declared, because the protocol says nothing about the model behind it |
supports_thinking | bool | discovered, or the protocol default | The model accepts extended thinking. On openai and openai-responses, the default is on only when reasoning_options declares levels |
requires_thinking | bool | false | For an API that rejects requests with thinking off. It implies supports_thinking and raises thinking to minimal effort when it is off, compaction included |
supports_vision | bool | false | The model accepts images. When false, image input and view_image are off |
supports_pdf | bool | false | anthropic and openai-responses only. The model reads a PDF that webfetch attaches inside its tool result. When it is off, webfetch returns the text of the PDF instead |
supports_cache_breakpoints | bool | false | openai-responses only. The endpoint honours an explicit prompt_cache_breakpoint, so the system prompt closes with one |
reasoning_options | table[] | unset | The reasoning controls the model takes, such as [{ type = "effort", values = ["low", "high"] }]. A type is toggle, effort with values, or budget_tokens with an optional min and max. [] declares that it takes none, so Caudra sends no reasoning level |
pricing_input | float | 0 | USD per million input tokens |
pricing_output | float | 0 | USD per million output tokens |
pricing_cache_write | float | 0 | USD per million tokens written to the prompt cache |
pricing_cache_read | float | 0 | USD per million tokens read from the prompt cache |
pricing_fast_input | float | unset | USD per million input tokens in fast mode |
pricing_fast_output | float | unset | USD per million output tokens in fast mode |
Model defaults
Section titled “Model defaults”A models entry only applies to the exact id it names. When a provider's ids change often, or discover_models finds models you never declared, put the shared settings in model_defaults instead:
[my-proxy.model_defaults]context_window = 229376max_output_tokens = 32768reasoning_options = []
[[my-proxy.models]]id = "smart-v1"max_output_tokens = 64000It takes the same fields as a models entry apart from id, and applies to every model of the provider including discovered ones. A matching models entry wins field by field, so smart-v1 above keeps the 229376-token window and raises only its output cap. Anything a model neither declares nor inherits falls back to discovery, then to the protocol default.
On an openai or openai-responses provider, a model gets a thinking level only from its declared reasoning_options. A model that declares no levels takes no thinking setting: Caudra sends no reasoning_effort, and the footer and task results show no level for it, because the endpoint would reject one it does not know. Declare the levels to offer them. On anthropic and google, reasoning_options = [] is a declaration, not an omission: it says the endpoint takes no reasoning controls. Leaving it unset there lets a thinking level chosen for another model reach an endpoint that may reject it.
A models entry whose id matches no live model is logged once: every setting on it is ignored, which otherwise looks like Caudra disregarding the config.
Custom slugs must not reuse a built-in provider name. A bad TOML parse exits with code 2 at startup so a typo cannot silently empty the registry. A bad edit while Caudra runs keeps the last valid file and shows the error, see Hot reload.
You can also create a custom provider interactively with caudra auth login and choosing the custom option. That writes a starter entry to this file.
Model limits on a built-in provider
Section titled “Model limits on a built-in provider”A built-in provider reads two model keys from this file: context_window and max_output_tokens. Set them in a [[SLUG.models]] entry for one model, or in [SLUG.model_defaults] for every model of the provider:
[[anthropic.models]]id = "claude-sonnet-4-6"context_window = 200000A models entry wins over model_defaults, and both win over the limits the provider lists, the model's curated entry in the model list, and the model list's catalog, in that order. A declared window is the total the prompt and the reply share, as on a custom provider, so compaction leaves room in it for the reply. The OpenAI Coding Plan still caps a declared window at the plan's own. On aperture, a declared window also wins over Aperture overrides.
An entry adds no model, and its id has to match the id in the model spec exactly. Every other model key on a built-in slug, such as supports_vision or a price, is ignored with a warning. Caudra reads an edit the next time it resolves the model, such as in a new session or after you pick the model again, see Hot reload.
Aperture overrides
Section titled “Aperture overrides”Aperture proxies upstream providers, exposing each model as aperture/<upstream>/<model>. Overrides keyed by upstream provider id live under [aperture.overrides]:
[aperture.overrides.llmserver]base = "llama-cpp"context_window = 131072max_output_tokens = 16384
[aperture.overrides.llmserver.models."qwen-3.6"]context_window = 262144supports_vision = trueProvider-level fields apply to every model from that upstream. Per-model entries under models win field by field, and take the same keys apart from models. Model ids containing dots must be quoted ("qwen3.6") since TOML treats a bare dotted key as a nested table.
| Field | Type | Default | Description |
|---|---|---|---|
context_window | integer | unset | Tokens of context |
max_output_tokens | integer | unset | The most tokens one response may hold |
supports_thinking | bool | unset | The models accept extended thinking |
supports_vision | bool | unset | The models accept images |
base | string | unset | The native provider an opaque upstream works like, such as llama-cpp, google, or anthropic. Caudra warns about a value it does not know and ignores it |
path_prefix | string | /v1, /v1beta for Gemini routes, none for Anthropic and Z.AI | The path Caudra sends ahead of each request, which Aperture appends to the upstream base URL. Set it to "" when that URL already has its own path |
models | table | {} | Overrides for single models, keyed by model id, which win key by key. Quote an id that holds a dot, such as models."qwen-3.6" |
Caudra sends /v1 (or /v1beta for Gemini routes, nothing for Anthropic and Z.AI), and Aperture appends that path to the upstream's base url. If an upstream base url already carries its own path, set path_prefix = "" for it to avoid a doubled path. Z.AI defaults to no prefix since its API path has no /v1 segment; point the upstream base url at the full API root (e.g. https://api.z.ai/api/paas/v4).
Accounts
Section titled “Accounts”[[SLUG.accounts]] entries list a provider's accounts in priority order, and [SLUG.switching] sets how Auto moves conversations between them. A table that holds only these two changes nothing else about a built-in provider:
[anthropic.switching]strategy = "paced"prefer_below = 25
[[anthropic.accounts]]name = "personal"
[[anthropic.accounts]]name = "api"fallback = trueA [SLUG.switching] table takes these keys:
| Field | Type | Default | Min | Max | Description |
|---|---|---|---|---|---|
strategy | string | ordered | - | - | How Auto picks an account. ordered takes the first usable account in accounts order and returns to it after its quota resets. paced takes the account furthest ahead of its quota schedule, so capacity that is about to reset gets used first |
switch_below | integer | 5 | 0 | 99 | The quota left in a watched window, in percent, below which a session moves to another account at its next request, even when that loses a warm prompt cache. It has to be lower than prefer_below |
prefer_below | integer | 20 | 1 | 100 | The quota left in a watched window, in percent, below which a session moves to another account once its prompt cache is cold anyway, such as in a new session or after compaction |
windows | string[] | every window the provider reports for the model | - | - | The quota windows the thresholds watch: 5h, weekly, and monthly |
Each [[SLUG.accounts]] entry takes these keys:
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | The account name, which caudra auth login --name saves a credential under and caudra auth use selects. It takes lowercase letters, digits, -, and _, and auto is reserved |
api_key_env | string | unset | The environment variable that holds this account's API key. Leave it out to use the credential caudra auth login saved |
fallback | bool | false | Let Auto move a subscription session onto this pay-per-token account, which it does only when every subscription is spent. A subscription account ignores it |
See How Auto switches for what the thresholds do.
A top-level [switching] table lets Auto move a conversation to another provider's subscription once its own provider's subscriptions run low. It is off until the table lists at least two providers:
[switching]providers = ["anthropic", "openai"]| Field | Type | Default | Description |
|---|---|---|---|
providers | string[] | required | The provider slugs Auto may move a conversation across, in the order it tries them, when every subscription of the conversation's provider is spent or running low. The conversation moves to a subscription account of the next provider with quota left, on a model of the same size, and comes back once its own provider has quota again. Leave the table out to keep every conversation on its provider |
See Across providers for which model the conversation moves to and when it comes back.
Decision endpoints
Section titled “Decision endpoints”The optional typed decision engine behind Auto mode, workflow decide() calls, and the decide() and rerank() helpers sends its requests to a decision endpoint. Each endpoint is a [decisions.<name>] table in this file. One endpoint is active at a time, and with none active the engine is off. The settings every endpoint shares, such as deadlines, features, and thresholds, stay in [decisions] in caudra.toml.
The quickest way to add one is caudra auth login --decision, or the Decision models section of /login. Both offer two presets, TypeSafe Jev (typesafe) and OpenAI Luna (openai), and a custom endpoint, which asks for a name, the protocol, the base URL, the model, and a key. Login writes the table, saves the key, and makes a new endpoint active. Logging in again to an existing endpoint replaces its key and keeps whichever endpoint is active. The presets write these tables:
[decisions.typesafe]protocol = "typesafe"base_url = "https://api.typesafe.ai"model = "jev-latest"api_key_env = "TYPESAFE_API_KEY"
[decisions.openai]protocol = "openai"base_url = "https://api.openai.com/v1"model = "gpt-6-luna"api_key_env = "OPENAI_API_KEY"| Field | Type | Default | Description |
|---|---|---|---|
protocol | string | required | Decision wire protocol: typesafe or openai. Never inferred from the URL or model. |
base_url | string | required | Decision API base URL. TypeSafe takes a root such as https://api.typesafe.ai and appends /v1/systemone. OpenAI takes a versioned base such as https://api.openai.com/v1 and appends /decisions. A path prefix stays, and a full endpoint is rejected. {env:NAME} reads the base from the environment. HTTPS is required, except for numeric loopback HTTP or with allow_http. No credentials, query, fragment, whitespace, or control characters. |
model | string | jev-latest for typesafe, gpt-6-luna for openai | Decision model identifier, nonblank and without control characters. |
api_key_env | string | unset | Environment variable holding the credential when no key is saved for this endpoint, never the credential itself. Project environment values are excluded. The presets set TYPESAFE_API_KEY and OPENAI_API_KEY. |
allow_http | boolean | false | Opt-in for plain HTTP to a non-loopback host. Use only with transport protection you control, such as a trusted encrypted tunnel. |
protocol = "typesafe" appends /v1/systemone to a root base URL. A path prefix stays in place, so a server mounted under /typesafe uses base_url = "http://127.0.0.1:8080/typesafe" and receives requests at /typesafe/v1/systemone. protocol = "openai" appends /decisions to a versioned base URL, such as https://api.openai.com/v1 for the hosted OpenAI Decisions API. Leave the appended path out of base_url, because a full endpoint is rejected.
Configuring an endpoint is the consent to send decision context to it, so HTTPS needs no other opt-in. Plain HTTP to numeric loopback, such as 127.0.0.1 or [::1], needs nothing either. Plain HTTP to any other host needs allow_http = true, which sends decision context and the key without TLS. Use it only with transport protection you control, such as a trusted encrypted tunnel. localhost is a DNS name for this rule, and private and CGNAT addresses get no exemption. For a local ninfer server, or one behind a tunnel, use the OpenAI protocol with the model name the server actually serves. decision-1 is not a Luna alias:
[decisions.local]protocol = "openai"base_url = "http://127.0.0.1:8080/v1"model = "decision-1"
[decisions.tunnel]protocol = "openai"base_url = "http://100.64.0.2:8080/v1"model = "decision-1"allow_http = trueRequests to an endpoint that is not a numeric loopback address go through the network proxy. Requests do not follow redirects. These settings do not change Workcell transport policy.
A key saved by login, in auth/decisions/<name>.json under the state directory, wins. Otherwise Caudra reads the global environment variable that api_key_env names, never a value from a project .env file. A custom endpoint has no api_key_env until you add one, and an endpoint with no key sends none, which suits a local server. To take the base URL from the environment, write base_url = "{env:TYPESAFE_BASE_URL}". The TYPESAFE_BASE_URL and OPENAI_BASE_URL variables do not change a decision endpoint on their own.
Switch the active endpoint with the Decisions row of /model, /decisions model, /decisions next (Ctrl+X d), or caudra decisions use <name|off>. caudra decisions list shows every endpoint, its key source, and which one is active. The choice is saved globally. A switch in the TUI applies to every open session of that process at once, and other Caudra processes and headless runs read it when they start. An edit to the active endpoint's table applies when you select the endpoint again or restart. When the active endpoint's table is gone, decisions are off and Caudra logs a warning that names it. caudra auth logout --decision <name> deletes the saved key and the table, and turns decisions off when that endpoint was active.
Decision prices
Section titled “Decision prices”Each decision call that reaches an endpoint counts toward /usage under the decision purpose, priced from the table below by the model id the endpoint answered with, then by the configured model. Prices are per 1M tokens, and a prompt past a threshold bills in full at that row's long rates. Answers Caudra reuses from its own cache cost nothing. A model outside the table, such as a local decision-1, adds its tokens without a cost, and Caudra counts it as an unpriced turn.
| Protocol | Models | Input | Cache read | Cache write | Output | Prompts past a threshold |
|---|---|---|---|---|---|---|
openai | gpt-6-luna | $0.10 | $0.01 | $0.125 | free | past 272K tokens: $0.20 input, $0.02 cache read, $0.25 cache write |
typesafe | jev-1.14, jev-1.13, jev-latest, jev-preview | $0.042 | free | free | free | same rates |
Some built-ins ship multiple plans (different base URLs or default models). caudra auth login <provider> asks which plan to use when more than one exists. You can also set it in TOML:
[mistral]plan = "coding"
[zai]plan = "coding"Current plans:
| Provider | Plan | What it does |
|---|---|---|
| Mistral | standard | Standard at https://api.mistral.ai/v1, default mistral/mistral-medium-latest |
| Mistral | coding | Vibe / Coding at https://api.mistral.ai/v1, default mistral/mistral-vibe-cli-latest |
| Z.AI | standard | Pay-as-you-go at https://api.z.ai/api/paas/v4, default zai/glm-5.3 |
| Z.AI | coding | Coding plan at https://api.z.ai/api/coding/paas/v4, default zai/glm-5.3 |
Env <SLUG>_BASE_URL still wins over both the plan and a base_url in this file.
Dynamic Providers
Section titled “Dynamic Providers”To add a custom provider or proxy, drop an executable script into the config providers/ directory (~/.config/caudra/providers/ on Linux/macOS, %APPDATA%\caudra\providers\ on Windows). The script must handle these subcommands:
| Subcommand | Timeout | What it does |
|---|---|---|
info | 5s | Return JSON with display_name, base provider, has_auth |
models | 5s | Return JSON array of model entries (optional) |
resolve | 30s | Return auth JSON (base_url, headers) |
login | interactive | OAuth or credential flow |
logout | interactive | Clear credentials |
refresh | 30s | Refresh auth tokens |
resolve is called each time a new agent spawns, so scripts should read tokens from disk instead of caching them in memory. That way auth changes from other processes get picked up.
The base field specifies which built-in provider to inherit the model catalog from. Valid values: anthropic, openai, google, copilot, copilot-enterprise, ollama, llama-cpp, mistral, zai, deepseek, openrouter, synthetic, tensorx, opencode, xai, aperture.
If your provider serves models not in the base catalog, add a models subcommand returning:
[{"id": "my-model-v2", "context_window": 200000, "max_output_tokens": 16384}]Only id is required. Optional fields: context_window (128K), max_output_tokens (16K), pricing ({input, output, cache_write, cache_read}, all per 1M tokens), supports_tool_examples (defaults to the base provider's setting), supports_thinking (defaults to the base provider's setting), requires_thinking (default false; for APIs that reject requests with thinking off, raises it to minimal effort and implies supports_thinking), supports_vision (defaults to the base provider's setting; when false, image input and the view_image tool are disabled). Without this subcommand, the base provider's models are used.
A llama-cpp model can replace Caudra's token-budget mapping with its native thinking fields. Each thinking mode maps to a JSON fragment merged into the request body:
[{ "id": "reasoning-model", "supports_thinking": true, "thinking_fields": { "off": {"reasoning_effort": "none"}, "adaptive": {"reasoning_effort": "medium"}, "low": {"reasoning_effort": "low"}, "medium": {"reasoning_effort": "medium"}, "xhigh": {"reasoning_effort": "xhigh"} }}]off is used when thinking is off, adaptive when thinking is on without a chosen level. Any other key is an effort level, one of none, minimal, low, medium, high, xhigh, max. The levels you declare are the ones the model accepts: whatever you ask for snaps into them, downwards first, so a level the model never advertised is never sent. Every part is optional.
Fragments are merged into the body, so nesting works too. A template toggle is just a fragment:
"thinking_fields": { "off": {"chat_template_kwargs": {"enable_thinking": false}}, "adaptive": {"chat_template_kwargs": {"enable_thinking": true}}}Named modes send only these fields, no token budget. An explicit /thinking <budget> snaps into the levels you declared; a model that declares none gets the adaptive fragment plus thinking_budget_tokens. Any mode you left undeclared falls back to the usual thinking_budget_tokens mapping, so no request ever ends up saying nothing. Models without thinking_fields keep the existing llama.cpp behavior.
Dynamic provider models are namespaced as {slug}/{model_id} (e.g. myproxy/claude-sonnet-4-6).
Script Name Rules
Section titled “Script Name Rules”- Must start with a letter or digit
- Only letters, digits, underscores, and hyphens after that
- Can't reuse a built-in provider's slug
- Must be executable