Skip to main content
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

The selected model must support tool calling for agent work.

Model profiles

A profile is a [models.NAME] table. stampede init writes two:
Keep top-level keys such as default above the first table header; a bare key after a header belongs to that table. Other per-profile keys (cache_ttl, observation_masking, retry_policy and a [models.NAME.prices] table) are listed in the configuration reference.

Anthropic

OpenAI

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:
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:
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.
stampede doctor prints one transport row per profile.

Roles

Use one profile per role. A person created with --model PROFILE runs on that profile, and its schedules run on it too:
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.

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:
/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:
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.