API Providers

stella is BYOK (bring your own key) and works with any vendor. There's no proxy in the middle, no markup, and each provider's native wire dialect is spoken directly. Switching vendors is just a --model flag.

# The same task, three vendors — no config change, no restart.
stella --model anthropic/claude-fable-5  run "add a retry to the upload path"
stella --model openai/gpt-5.5            run "add a retry to the upload path"
stella --model deepseek/deepseek-chat    run "add a retry to the upload path"

The matrix

Detection rank is the order auto-detection tries providers in. The default model is what you get when you name none.

Catalog pricing

List prices come from the built-in seed catalog, in USD per million tokens. stella models refresh re-syncs them from models.dev.

The model guide covers which model fits which seat.

Reasoning and effort support

reasoning and effort are set per agent in agent_engine_config. What actually reaches the wire differs by provider. If a provider can't express a parameter, stella drops it instead of failing the request:

Auto-detection

With no --model and no configured default, stella picks the first provider in the matrix above that has a usable credential.

A settings-configured default_model sits between the --model flag and auto-detection: an explicit flag wins, but a configured default beats "first provider with a key."

{
  "agent_engine_config": {
    "default_model": "anthropic/claude-fable-5"
  }
}

The credential chain

For the selected provider, the API key resolves in this order — first hit wins:

1. --api-key
2. The provider's env var, plus aliases
3. settings.json providers.<id>.api_key
4. ~/.stella/credentials.toml
5. An interactive prompt on a TTY — the entered key is saved, so you are prompted once

stella models prints which link answered for each provider (env:ANTHROPIC_API_KEY, a dotenv filename, credentials.toml, or settings.json).

Two settings.json fields reroute steps 2 and 3:

• providers.<id>.api_key_env renames the primary credential var; the original demotes to an alias and keeps working.
• providers.<id>.api_key embeds the key literal inline.

{
  "providers": {
    "anthropic": { "api_key_env": "MY_TEAM_ANTHROPIC_KEY" }
  }
}

Custom base URLs

Every built-in provider accepts a base_url override for a gateway or proxy. The wire dialect does not change with it.

{
  "providers": {
    "anthropic": { "base_url": "https://llm-gateway.internal.example.com" }
  }
}

--base-url (env form STELLA_BASE_URL) does the same for one run and outranks the settings value.

Per-provider differences

Everything above is shared. These are the differences worth knowing.

Anthropic

Prompt caching works fully here: stella meters both cache reads and cache writes, so Observatory figures reflect the true bill. Cached input bills at $0.30/Mtok against a $3.00 list price, a 10x discount on the stable prefix the context engine maintains.

The cache window is the one setting here you may want to change. Anthropic holds a written prefix for 5 minutes by default and offers a 1-hour window per request. stella picks based on the surface: stella chat and stella resume ask for the hour, every headless run keeps the 5-minute default. The reason is cost — a 1-hour write bills at 2x the input rate against the short window's 1.25x, and that premium only pays off when turns are far enough apart to lose the prefix. An eviction is the expensive event: it re-bills the whole prefix at the write rate and loses the 10x read discount on it. Interactive turns sit minutes apart, so the wider window is close to free insurance; a headless run's calls are seconds apart and would pay the premium for a prefix that was never going to expire. Override either default with providers.anthropic.cache_ttl ("5m" or "1h").

Server-side context editing is off, and there is no setting for it. The Messages API can drop old tool results and thinking blocks from a chat before the model reads it. stella can ask for that, and does not: the trigger that decides when clearing starts has never been measured, and each edit throws away the cached prefix from the point of the edit. A cache read bills at $0.30/Mtok against a write at $3.75/Mtok, so a trigger picked by taste moves the bill more than tenfold in the direction you did not want. The decision is recorded in ADR 0026, and it holds until a panel measures the number.

params.max_tokens defaults to 32000 with thinking on, 4096 with it off. Adaptive thinking spends from the same output allowance as the answer, so without this, a max-effort verifier could get cut off mid-verdict. A value you set is used exactly as given.

OpenAI

Two parameters only this provider puts on the wire:

Every other adapter drops both silently, so they're only worth setting on an OpenAI-routed agent. The built-in openai dialect is fixed to OpenAI Responses, so a custom base_url must speak it too (Azure's /openai/v1 surface does). For a gateway that only speaks the older chat completions format, define a custom provider id instead.

Google Gemini

The 1M-token window is the reason to reach for it: whole-repo comprehension, long-log analysis, giant-diff review. Give it a task that needs that much room:

stella --model gemini/gemini-3-pro run \
  "read every module under src/ingest and write a design note on where retries are handled inconsistently"

Google Vertex AI

Same models, same dialect as Gemini. The difference is governance: inference runs inside your GCP project, billed to your account, under your own IAM and data-residency controls.

export VERTEX_ACCESS_TOKEN=$(gcloud auth print-access-token)
export VERTEX_PROJECT_ID=my-gcp-project        # or GOOGLE_CLOUD_PROJECT
export VERTEX_LOCATION=global                  # optional; this is the default

Access tokens expire after about an hour. Wrap the export so a fresh one is a keystroke away:

# ~/.zshrc or ~/.bashrc
stella-vertex() {
  VERTEX_ACCESS_TOKEN="$(gcloud auth print-access-token)" stella "$@"
}

Amazon Bedrock

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...        # STS/SSO-derived credentials only
export AWS_REGION=us-east-1         # or AWS_DEFAULT_REGION; default us-east-1

The default model is a cross-region inference profile, not a bare model id: Bedrock rejects on-demand calls to newer Anthropic models without one. The real host is region-scoped (bedrock-runtime.<AWS_REGION>.amazonaws.com) and built per request.

xAI

The seeded default is grok-4.3: xAI's flagship on its published model list, with the largest context in the current lineup and its lowest price.

grok-4.3 prices in two tiers — the catalog carries the below-200k-input figures, so a turn that crosses that boundary is costed low rather than high. grok-4.6 is a newer model for coding and agentic work, at roughly 1.6x the input price and 2.4x the output price; pin it under providers.xai.default_model if that trade is worth it to you.

DeepSeek

The lowest price in the catalog among hosted models, and a natural choice for triage in any lineup. deepseek-chat is the non-thinking model; deepseek-reasoner is the reasoning one.

Z.ai

A GLM coding plan puts your quota on a dedicated endpoint — https://api.z.ai/api/coding/paas/v4 instead of the pay-per-token https://api.z.ai/api/paas/v4. Same key, same models, a flat subscription instead of a meter.

export ZAI_API_KEY="..."
export ZAI_GLM_CODING_PLAN=1
stella config    # Base URL must read https://api.z.ai/api/coding/paas/v4

Or set it permanently in user scope:

{
  "providers": {
    "zai": { "base_url": "https://api.z.ai/api/coding/paas/v4" }
  }
}

On a coding plan the $ figures in stella stats are notional — stella prices tokens at catalog list rates, but you pay the flat subscription. Token counts, step counts, and cross-model $/resolved comparisons stay meaningful; absolute dollars for zai/* do not. --spend-limit also caps against those notional prices.

OpenRouter

One key, every vendor. Gateway slugs are vendor/model and pass through unseeded: any slug the gateway serves works exactly as written, and a typo fails with OpenRouter's own 400/404 error instead of a stella error. The default model is moonshotai/kimi-k3.

The default posture

One key reaches every vendor, so on OpenRouter the interesting question isn't which model, but which model for which role, since each role wants genuinely different things. With no configuration at all, an OpenRouter instance runs:

Note the verifier is a different family from the driver. stella already treats cross-family judging as the goal (see auto_mode) — this default just does that without asking you to configure anything.

This is a starting point, not a lock. It sits underneath the whole agent_engine_config scope chain, so any field you set is yours — set default_model and the session model is whatever you said, while the rest of the posture stays. It also applies only when OpenRouter is the provider that actually got picked: run --model anthropic/… with an OpenRouter key present and you get an Anthropic session, with no part of this routed through the gateway.

Pinning the upstream

A gateway is a router, not a vendor: OpenRouter picks the upstream that actually serves a request based on app identity, and it is free to choose a different one between two calls to the same slug. In one test, a probe carrying stella's own attribution asked for anthropic/claude-sonnet-5 and was served by provider: Amazon Bedrock. This is invisible in the ordinary case: you asked for a model family, and you got it. But it means the model provider behind an OpenRouter-routed run is not something a bare --model pins.

--upstream-pin <vendor> (env STELLA_UPSTREAM_PIN, repeatable or comma-separated) fixes it: the request carries provider: {order: [...], allow_fallbacks: false}, so OpenRouter either serves it from the named vendor, in the order given, or the call fails rather than silently routing elsewhere.

stella run "…" --model openrouter/anthropic/claude-fable-5 \
  --upstream-pin z-ai --upstream-pin anthropic

Use this whenever two runs need to be the same experiment — a before/after comparison, a head-to-head against another agent, or anything where "which vendor actually answered" needs to stay fixed. See the terminal-bench head-to-head guide for an example. This does nothing on any provider that is not a gateway — a direct anthropic/… or openai/… session has no routing step to pin.

Selecting models

stella --model openrouter/moonshotai/kimi-k3       run "tidy the changelog"
stella --model openrouter/openai/gpt-5.5           run "review this diff as a strict verifier"
stella --model openrouter/anthropic/claude-fable-5 run "refactor the scheduler"
stella --model openrouter/openrouter/auto          run "let the gateway pick per request"

Two routing forms:

With provider set, model goes to that provider exactly as written, with no splitting — which is what lets an OpenRouter slug contain a / of its own.

Verifier-diversity logic does not treat "openrouter" as one family: an OpenRouter spec's family is the routed slug's vendor prefix, so openrouter/openai/gpt-5.5 counts as OpenAI, and cross-family preference works through the gateway too.

Local servers

Any OpenAI-compatible endpoint you run yourself: Ollama, vLLM, LM Studio, llama.cpp. Never auto-detected — --base-url (or STELLA_BASE_URL) is required every time.

stella --model local/llama3.3      --base-url http://localhost:11434/v1 chat  # Ollama
stella --model local/qwen2.5-coder --base-url http://localhost:8000/v1 run "…"  # vLLM

A bearer token is always sent (the placeholder local when LOCAL_API_KEY is unset), so key-checking servers fail loudly instead of mysteriously. Local slugs skip catalog validation: any model name your server knows is accepted.

The id local is reserved and cannot be redefined in settings.json, which is why --base-url is always required with it. To bake an endpoint into config instead, define your own provider under a non-reserved id:

{
  "providers": {
    "ollama": {
      "base_url": "http://localhost:11434/v1",
      "default_model": "llama3.3",
      "api_key": "local"
    }
  }
}

• dialect defaults to openai-compatible. anthropic, gemini, and openai-responses are also available; vertex and bedrock are rejected for custom ids, because those dialects need credential resolution a settings entry cannot express.
• A config-defined provider reads its key from a derived env var: the id uppercased with anything outside [A-Za-z0-9] folded to _, plus _API_KEY (my-gateway reads MY_GATEWAY_API_KEY). api_key_env names a different one.
• It auto-detects (after every built-in) only when it has a default_model.

Local models have no catalog prices, so stella stats dollar columns read zero. Tokens, steps, and resolve-rate comparisons still work; --spend-limit has nothing to meter against.

Next

• Model guide — which model fits which seat
• Examples — ready-made lineups from max-quality to dirt-cheap
• Agent engine config — per-agent model, provider, and effort