API Providers

Stella is BYOK — bring your own key — and vendor-agnostic by construction. There is no proxy in the middle and no markup on your tokens: Stella speaks each provider's native wire dialect directly — Anthropic Messages, OpenAI Responses, Gemini generateContent, Bedrock Converse, and the OpenAI-compatible dialect the rest of the field converged on. Switching vendors is a --model flag, not a migration.

The provider matrix

Each provider name links to its dedicated page — setup, model selection, provider-specific configuration, and catalog pricing. For a quick first-run walkthrough, see Providers & models.

Auto-detection

With no --model flag and no configured default, Stella selects the first provider that has a resolvable credential, in this preference order:

1. zai
2. anthropic
3. openai
4. xai
5. deepseek
6. gemini
7. openrouter
8. vertex and bedrock — last, deliberately

The "configured default" above is a real resolution layer with a name: agent_engine_config's default_model. It sits between the --model flag and auto-detection — an explicit flag always wins, but a settings-configured default beats "first provider with a key":

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

The credential chain

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

1. The --api-key flag (requires an explicit --model provider/...)
2. The provider's env var, plus aliases — e.g. GOOGLE_API_KEY for Gemini
3. settings.json providers.<id>.api_key
4. ~/.config/stella/credentials.toml
5. An interactive prompt (on a TTY) — the entered key is saved to credentials.toml, so you are only prompted once

See Credentials for the file format and the fine print.

Overriding the key source

Two settings.json fields reroute steps 2 and 3 of the chain — every provider page's "reference an env var" option is this mechanism, documented once here:

• providers.<id>.api_key_env renames the provider's primary credential var: the named var becomes the one Stella checks first, and the original (ANTHROPIC_API_KEY, OPENAI_API_KEY, …) demotes to an alias — so the standard var keeps working as a fallback.
• providers.<id>.api_key embeds the key literal inline — step 3 of the chain. Fine for a scratch machine; credentials.toml is the better home for anything long-lived.

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

Where to go next

• Choosing a model — the Model guide is the master catalog: context windows, list prices, and which model fits which role.
• Tuning profiles — Examples has ready-made lineups from max-quality to dirt-cheap.
• Per-agent routing — Agent engine config gives each engine agent (worker, judge, triage) its own model, provider, and effort — including a different gateway per agent.