> ## Documentation Index
> Fetch the complete documentation index at: https://stampede.autonomousorganizations.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Providers and models

> Configure model profiles for the Anthropic and OpenAI APIs, OpenAI-compatible servers, and the Claude and Codex session providers, with roles, fallback and key storage.

Stampede calls a model through a provider. It speaks the Anthropic Messages API and the OpenAI Chat Completions API, reaches any OpenAI-compatible server (Ollama, vLLM) through a base URL, and can drive the `claude` or `codex` command-line tools as session providers. Each way of reaching a model is written as a model profile in `~/.stampede/config.toml`.

## Providers

| `provider` | What it talks to | Default `base_url` |
| - | - | - |
| `anthropic` | The Anthropic Messages API | `https://api.anthropic.com` |
| `openai` | The OpenAI Chat Completions API, or any compatible server | `https://api.openai.com` |
| `session` | The `claude` or `codex` CLI, signed in with its own subscription | none |

The selected model must support tool calling for agent work.

## Model profiles

A profile is a `[models.NAME]` table. `stampede init` writes two:

```toml theme={null}
default = "sonnet"

[models.sonnet]
role = "primary"
provider = "anthropic"
model = "claude-sonnet-5"
key_env = "ANTHROPIC_API_KEY"

[models.openrouter]
role = "fallback"
provider = "openai"
model = "openai/gpt-5.6-sol"
base_url = "https://openrouter.ai/api"
key_env = "OPENROUTER_API_KEY"
```

Keep top-level keys such as `default` above the first table header; a bare key after a header belongs to that table.

| Key | Meaning |
| - | - |
| `provider` | `anthropic`, `openai` or `session`. |
| `model` | The model id sent to the server, exactly as the server names it. |
| `base_url` | The server. For `openai`, give the base without `/v1`; the provider appends `/v1/chat/completions`. |
| `key_env` | The name of the variable that holds the key, never the key itself. |
| `command` | For `session`: `claude` or `codex`. |
| `effort` | `"low"`, `"medium"` or `"high"`. Sent as reasoning effort in the form each provider takes. |
| `role` | `primary`, `fallback`, `subagent` or `orchestrator`. See [Roles](#roles). |
| `timeout_secs` | Wall-clock limit of one turn on this profile. Default 300 seconds, 1800 for a session provider. |
| `context_window_tokens` | The context size to assume. Set it on every local profile. |
| `failover_compatibility` | Which histories may move to a different provider on fallback: `canonical_tools` (default), `text_only` or `same_dialect`. |
| `stream_terminal_profile` | What counts as the end of a streamed reply, for a server that needs something other than the default. |
| `prefer` | Transport order for a profile with several transports. Default: `key`, `session`, `local`. |

Other per-profile keys (`cache_ttl`, `observation_masking`, `retry_policy` and a `[models.NAME.prices]` table) are listed in the [configuration reference](https://stampede.autonomousorganizations.ai/reference/configuration.md).

### Anthropic

```toml theme={null}
[models.sonnet]
provider = "anthropic"
model = "claude-sonnet-5"
key_env = "ANTHROPIC_API_KEY"
```

### OpenAI

```toml theme={null}
[models.gpt]
provider = "openai"
model = "gpt-5"
key_env = "OPENAI_API_KEY"
```

### OpenAI-compatible servers

Point `base_url` at the server. The model id must be exactly the one the server loaded (for Ollama, as `ollama list` prints it). A profile with a custom `base_url` and no `key_env` sends no key. A server that wants a key gets it through `key_env`:

```toml theme={null}
[models.local]
provider = "openai"
model = "qwen3:32b"
base_url = "http://localhost:11434"
context_window_tokens = 32000

[models.runner]
provider = "openai"
model = "the-id-vllm-serves"
base_url = "http://100.64.0.9:8000"
key_env = "SELF_HOSTED_LLM_KEY"
```

Set `context_window_tokens` on a local profile, and make the server's own context length at least that large (for Ollama, `OLLAMA_CONTEXT_LENGTH` or the model's setting). Otherwise the server can silently drop the start of the prompt.

A router that fronts many vendors behind the OpenAI API, such as the `openrouter` profile above, works the same way. Give the base URL without `/v1`.

### Session providers

A session provider runs the `claude` or `codex` CLI that is installed and signed in on the machine, so Stampede needs no API key for it:

```toml theme={null}
[models.claude-cli]
provider = "session"
command = "claude"
model = "claude-sonnet-5"
effort = "high"
```

Know these limits before you choose one:

* The CLI runs its own agent loop with its own tools and permissions. Stampede's tools, presets and path roots are not offered to a session model, and Stampede relays only the CLI's final answer.
* Stampede runs the CLI with your rights.
* One turn is one opaque attempt. If the process is interrupted after it starts, the outcome is recorded as unknown, and the turn is not retried automatically.
* `codex` reports no token usage, so its usage shows as unknown.
* The default turn limit is 1800 seconds.

### Multiple transports

One profile can reach the same model in more than one way. Stampede takes the first transport that is usable right now: `key` when its variable resolves, `session` when the command is on the path, `local` when a base URL is set.

```toml theme={null}
[models.sonnet]
role = "primary"
prefer = ["key", "session"]

[models.sonnet.key]
provider = "anthropic"
model = "claude-sonnet-5"
key_env = "ANTHROPIC_API_KEY"

[models.sonnet.session]
command = "claude"
model = "claude-sonnet-5"
effort = "high"
```

`stampede doctor` prints one transport row per profile.

## Roles

| Role | Used for |
| - | - |
| `primary` | The startup profile when `default` is not set. |
| `fallback` | Tried when the active provider fails, if it is a different provider and model. |
| `subagent` | Every [sub-agent](https://stampede.autonomousorganizations.ai/teamwork/sub-agents.md). Absent, sub-agents run on the parent's model. |
| `orchestrator` | Drives `stampede agent` and goal episodes, with an instruction to delegate first. Absent, agent mode runs on the default profile. |

Use one profile per role. A person created with `--model PROFILE` runs on that profile, and its schedules run on it too:

```bash theme={null}
stampede person create analyst --purpose "Summarises reports" --policy research --model haiku
stampede person edit analyst --model sonnet
```

In the TUI, `/model` lists the profiles and `/model NAME` switches the conversation to one for future turns.

### Selection order

At startup the profile is chosen in this order: explicit `STAMPEDE_*` environment variables, then the profile named by `STAMPEDE_PROFILE`, then `default`, then the profile with `role = "primary"`, then built-in defaults.

### Fallback

When a call to the active provider fails, the `fallback` profile is tried. Once the fallback has answered a call the active provider failed, the rest of that run stays on the fallback, so a provider that is down is not retried on every turn. The next run tries the active provider first again. `failover_compatibility` on the profile decides whether a conversation with tool calls may move between the Anthropic and OpenAI formats.

## Key storage

A key never appears in `config.toml`. The profile names a variable in `key_env`, and Stampede resolves it from the environment first, then from the secret vault. A cloud profile without `key_env` uses the provider's standard variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).

### The env file

`~/.stampede/env` holds one `KEY=value` per line and is loaded at startup by every command and every worker. It must be a regular file you own with mode `0600`, in a `0700` directory; anything looser stops the command with the path and the `chmod` to run. A variable already set in the real environment wins.

```bash theme={null}
touch ~/.stampede/env && chmod 600 ~/.stampede/env
# then add lines with an editor:
# ANTHROPIC_API_KEY=...
# OPENROUTER_API_KEY=...
```

### The secret vault

`~/.stampede/secrets.enc` is an encrypted store, unlocked by `STAMPEDE_SECRET_KEY` (put that in the env file). Manage it from the console:

```text theme={null}
/add-secret OPENROUTER_API_KEY=sk-or-...
/secrets
/rm-secret OPENROUTER_API_KEY
```

`/secrets` lists names only. The model never reads the vault.

## Applying changes

The configuration is read when a process starts. After editing profiles, start a new console and restart the workers:

```bash theme={null}
stampede doctor
stampede service restart
```

The agent can add a profile for you with its `save_model_profile` tool, within limits: it may only send a key where the file already sends that key, and a session profile it writes may name only `claude` or `codex`. To use a new server or a new key variable, add the profile to the file yourself and restart.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.