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:
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
Pointbase_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:
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 theclaude or codex CLI that is installed and signed in on the machine, so Stampede needs no API key for it:
- 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.
codexreports 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:
/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: explicitSTAMPEDE_* 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, thefallback 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 inconfig.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: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.