> ## 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.

# Configuration reference

> Every table and key of ~/.stampede/config.toml in v0.5.3 with type, default and meaning, and the keys of the env file.

Stampede reads all of its settings from `~/.stampede/config.toml` and all of its secrets from the env file or the encrypted vault. This page lists every table and key that v0.5.3 accepts, with its type and default. The guides explain when to use them: [Model providers](https://stampede.autonomousorganizations.ai/models/providers.md), [MCP servers](https://stampede.autonomousorganizations.ai/models/mcp.md), [Limits](https://stampede.autonomousorganizations.ai/models/limits.md), [Telegram setup](https://stampede.autonomousorganizations.ai/start/telegram-setup.md), [Webhooks](https://stampede.autonomousorganizations.ai/start/webhooks.md).

## Rules for the file

* The file must be a regular file you own, mode 0600, inside the 0700 home. A symlink, another owner or a group or world bit stops every command with an error naming the path.
* A missing file means the built-in defaults. `stampede init` writes the file on a fresh install.
* Unknown keys are refused at load, by name, at the top level and inside `[tools]`, `[node]`, `[rooms]`, `[persons.NAME]`, `[gateway.telegram]` and `[webhook]`. A file that uses a key from a newer release does not load on an older binary.
* Keep top-level keys above the first table header. A bare key written after a header belongs to that table.
* A secret never appears in this file. Profiles name the variable that holds a key (`key_env`); the gateway names the variable that holds the bot token (`token_env`); webhook routes name vault entries.
* Workers read the file once at start. After an edit, run `stampede service restart` (the gateway's member and group lists also reload on their own; see below).

Keys marked owner-only are refused by the model-facing configuration tools, so only you can set them by editing the file.

## Top-level keys

| Key | Type | Default | Meaning |
| - | - | - | - |
| `default` | string | none | The profile used when nothing else selects one. Without it, the first profile with `role = "primary"` in name order. |
| `resume_by_default` | bool | `false` | Bare `stampede` continues the last conversation. `stampede chat` and `stampede tui` always start fresh. |
| `console` | `"tui"` or `"chat"` | `"tui"` | What bare `stampede` opens when stdin and stdout are both a terminal. Without a terminal it is always the line chat. Owner-only. |
| `self_improve` | bool | `false` | Run a reflection pass when a chat exits cleanly, which may save memory notes or skills. It is a billed model turn. |
| `unattended_delegation` | bool | `false` | Lets a headless run decided by the host's grants (`stampede agent`, a piped `stampede chat`, a goal episode) call `run_subagent` and `run_subagents`. Person runs follow the person's policy instead. Owner-only. |

Startup precedence for the model: explicit `STAMPEDE_*` environment variables, then the profile named by `STAMPEDE_PROFILE`, then `default`, then the primary role, then built-in defaults.

## `[tools]`

Bounds Stampede's own file tools and the size of one turn. Owner-only for `full_access` and `require_approval`.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `full_access` | bool | `true` | `true`: the file tools read and write any path, and `run_command` and `start_command` run any program in the operator's own runs. `false`: the file tools stay inside the configured roots. `stampede init` writes it explicitly. |
| `read_paths` | list of strings | `[]` | Extra read-only roots. A relative entry resolves under `~/.stampede`. |
| `write_paths` | list of strings | `[]` | Extra read and write roots. With exactly one entry, it is the workspace of schedule fires, webhook runs and remote requests. |
| `require_approval` | bool | `false` | Confirm every tool call in an attended chat. A chat with no one to answer (piped stdin) is refused every tool call. |
| `turn_model_calls` | integer, 2 to 100 | `26` | Model calls one turn may make. Two are kept to conclude the turn, so 24 ordinary calls by default. |
| `turn_input_tokens` | integer, 100,000 to 5,000,000 | `500000` | Input tokens one turn may send across its calls, cache reads included. |
| `project_instructions` | bool | `true` | Load `AGENTS.md`, `CLAUDE.md`, `STAMPEDE.md` and `~/.stampede/instructions.md` into runs. |

A request from a paired machine gets at most the default of `turn_model_calls` and `turn_input_tokens`, whatever this file sets. Paths bound the file tools only; a program a person may run acts with your rights outside every root. A root at or above `~/.stampede` grants nothing inside it, and `stampede doctor` shows it as a failed `state directory` row.

## `[models.NAME]`

One table per model profile. `NAME` is any key; plain ASCII letters, digits, `_` and `-` are the readable choice. A profile declares its transport inline (flat form) or in sub-tables.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `role` | `"primary"`, `"fallback"`, `"subagent"`, `"orchestrator"` | none | Primary: startup model when `default` is unset. Fallback: tried when the active provider fails. Subagent: model for child runs. Orchestrator: drives `stampede agent` and goal episodes. One profile per role. |
| `provider` | `"anthropic"`, `"openai"`, `"session"` | none | The API dialect. `openai` speaks Chat Completions and works with any compatible server. `session` drives the `claude` or `codex` CLI. |
| `model` | string | provider default (`claude-sonnet-5`, `gpt-5`) | The model id exactly as the server names it. |
| `base_url` | string | `https://api.anthropic.com`, `https://api.openai.com` | The server, without `/v1`. A custom `base_url` with no `key_env` sends no key. |
| `key_env` | string | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | Name of the variable holding the key, resolved from the environment, then the vault. |
| `command` | string | `"claude"` | The CLI a session profile drives. |
| `effort` | `"low"`, `"medium"`, `"high"` | none | Reasoning effort, sent in the form the provider and model take. |
| `prefer` | list of `"key"`, `"session"`, `"local"` | `["key", "session", "local"]` | Transport order for a multi-transport profile. |
| `timeout_secs` | integer | 300 (1,800 for a session provider) | Wall-clock ceiling on one turn. |
| `context_window_tokens` | integer | by model name: 200,000 `claude*`, 400,000 `gpt-5*`, 128,000 other `gpt-*`, 32,000 names containing `qwen`, otherwise 128,000 | Context window the harness counts against. Set it on every local profile. |
| `cache_ttl` | `"auto"`, `"5m"`, `"1h"`, `"off"` | `"auto"` | Prompt-cache retention to ask for. `auto` asks for one hour on unattended runs and five minutes on interactive turns. Owner-only. |
| `observation_masking` | `"off"` or `{ keep = N, trigger = F }` | `"off"` | Replace older tool results with a placeholder once they exceed a share of the window. `keep` defaults to 5 (at least 1), `trigger` to 0.2 (above 0, at most 1). |
| `stream_terminal_profile` | `"anthropic_message_stop"`, `"open_ai_done"`, `"open_ai_finish_reason"`, `"open_ai_done_or_finish_reason"`, `"opaque_process_exit"` | by provider | What must arrive before the end of a stream counts as a complete reply. OpenRouter needs no value. |
| `failover_compatibility` | `"canonical_tools"`, `"text_only"`, `"same_dialect"` | `"canonical_tools"` | Which conversation histories may move to a different provider dialect on failover. |
| `retry_policy` | table | see below | Retries on the same route. Failover to another profile is separate. |

### Transport sub-tables

`[models.NAME.key]`, `[models.NAME.session]` and `[models.NAME.local]` each describe one way to reach the model. The first usable one in `prefer` order wins.

| Table | Keys it uses | Usable when |
| - | - | - |
| `key` | `provider`, `model`, `key_env`, `base_url` | The named variable resolves, or the endpoint is custom and keyless. |
| `session` | `command`, `model`, `effort` | The command is on `PATH`. |
| `local` | `model`, `base_url` (provider defaults to `openai`) | A `base_url` is set. |

A transport table also accepts `context_window_tokens`, `stream_terminal_profile`, `retry_policy`, `failover_compatibility`, `cache_ttl` and `observation_masking`.

```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"
```

### retry\_policy

All four keys are required when the table is present.

| Key | Type | Default | Limit |
| - | - | - | - |
| `max_same_route_retries` | integer | `2` | at most 16 |
| `base_delay_millis` | integer | `250` | above 0, at most `max_delay_millis` |
| `max_delay_millis` | integer | `10000` | at most 300,000 |
| `jitter_percent` | integer | `20` | at most 50 |

### `[models.NAME.prices]`

US dollars per million tokens, used by `stampede usage`, `runs show --tokens` and `/cost`. Each key is optional, but a call is priced only when every component it carries has a price. Owner-only.

| Key | Type | Meaning |
| - | - | - |
| `input` | number | Uncached prompt tokens. |
| `output` | number | Output tokens. |
| `cache_read` | number | Cache-read prompt tokens. |
| `cache_write_5m` | number | Five-minute cache writes. |
| `cache_write_1h` | number | One-hour cache writes. |

### Defaults written by init

```toml theme={null}
[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"
```

## `[[mcp]]`

One table per MCP server. Its tools join the model's set, prefixed with the label (`github__search`).

| Key | Type | Default | Meaning |
| - | - | - | - |
| `label` | string | required | Prefix of the server's tool names. |
| `command` | string | required | Program to start. It runs with your rights. |
| `args` | list of strings | `[]` | Arguments. |
| `env_passthrough` | list of strings | `[]` | Names of variables passed to the server. The server gets a minimal environment plus exactly these. |

## `[node]`

| Key | Type | Default | Meaning |
| - | - | - | - |
| `delivery_ttl_hours` | integer, 1 to 720 | `24` | How long a cross-machine request this machine could not deliver stays queued for retry. Fixed on the request when it is submitted. |

## `[rooms]`

Bounds on task rooms. Owner-only.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `wake_limit` | integer | `64` | Wakes one room may cause in all. At the limit the room closes. `0` closes every room as it opens. |
| `member_wake_limit` | integer | `16` | Wakes one member may receive in one room. Does not apply to the coordinator. |
| `wake_wait_secs` | integer | `300` | How long a wake may wait for a run to take it before it is reported. |

## `[persons.NAME]`

Settings for one person. `NAME` is compared without case; `[persons.main]` is the operator's own person. A table that names no person changes nothing.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `project_instructions` | bool | `true` | `false` loads no project instruction file in this person's runs. It cannot turn loading on against `[tools] project_instructions = false`. |
| `auto_load` | list of strings | `[]` | Skill names pinned into every model request of this person's runs. At most two load, within 16,384 bytes of bodies, in list order. |

## `[gateway.telegram]`

The Telegram gateway. Absent, no gateway worker is installed. The whole `[gateway]` table is owner-only.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `token_env` | string | required | Name of the variable holding the bot token, set in the env file or the worker's environment. |
| `workdir` | absolute path | required | The worker's directory and the directory grant of every request's run. Must exist and sit outside `~/.stampede` without containing it. |
| `requests_per_hour` | integer, 1 to 1000 | `20` | Requests one member may make per hour. |
| `api_base` | string | none | Test hook only: `http://127.0.0.1:PORT` or `http://[::1]:PORT`. Absent, the worker uses the Bot API. |

### `[[gateway.telegram.member]]`

At least one, at most 256.

| Key | Type | Meaning |
| - | - | - |
| `telegram_user_id` | positive integer | The member's numeric Telegram id. Unique. |
| `person` | string | The requester person that stands for the member. Unique, must exist, not `main`. It never runs a model. |

### `[[gateway.telegram.group]]`

Optional, at most 64. Absent, the bot serves private chats only.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `chat_id` | negative integer | required | The group or supergroup id (supergroups start with `-100`). Unique. |
| `persons` | list of strings | `[]` | The persons the group's members may address. Empty means every non-requester person. |

The running gateway reloads `member` and `group` after every poll and on `stampede service reload`. `token_env`, `workdir`, `requests_per_hour` and `api_base` take effect at the next restart.

## `[webhook]`

The signed webhook listener. Absent, or with no route, no webhook worker is installed. The whole table is owner-only.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `bind` | string, `IP:PORT` | `"127.0.0.1:8787"` | Listen address. |
| `allow_non_loopback` | bool | `false` | Required to bind anything other than a loopback address. |
| `max_body_bytes` | integer, 1,024 to 1,048,576 | `262144` | Largest request body accepted. |

### `[[webhook.route]]`

| Key | Type | Default | Meaning |
| - | - | - | - |
| `name` | string | required | 1 to 64 lowercase letters, digits, `-` or `_`. Served at `/hooks/NAME`. Unique. |
| `sender` | `"github"`, `"gitlab"`, `"linear"`, `"generic"` | required | How the delivery is verified. |
| `secret_name` | string | required | Vault entry holding the signing secret (uppercase letters, digits, `_`; the value at least 32 bytes). |
| `events` | list of strings | `[]` | Events the route accepts, such as `issues.labeled`. Empty accepts every event, so always list them. |
| `match` | table of string to string | `{}` | Payload fields that must equal the given values, such as `{ "label.name" = "stampede" }`. |
| `person` | string | required | The person that runs the delivery. Must not be free, operator or maintainer. |
| `template` | string | required | The task text placed before the payload fields. |
| `fields` | list of strings | `[]` | Payload field paths passed to the model, each up to 128 characters. |
| `destination` | `"comment"` or `"record"` | required | Post the result as a comment, or keep it on the run. |
| `repositories` | list of strings | `[]` | Comment routes only, required: each `OWNER/NAME` the route may comment on. |
| `token_name` | string | none | Comment routes only, required: vault entry holding the `gh` or `glab` token. |

A `comment` route needs a `github` or `gitlab` sender, and its events must all be issue events or all be pull or merge request events.

## Env file

`~/.stampede/env` holds one `KEY=value` per line, mode 0600. Every command and worker loads it once at startup. A variable already set in the real environment wins.

| Variable | Meaning |
| - | - |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY` | Provider keys. Any variable a profile's `key_env` names works the same way. |
| `TELEGRAM_BOT_TOKEN` (or the name in `token_env`) | The bot token. The vault does not resolve it. |
| `STAMPEDE_SECRET_KEY` | Passphrase of the encrypted vault `~/.stampede/secrets.enc`. Absent, the vault is skipped. |
| `STAMPEDE_PROFILE` | Start on this profile instead of `default`. |
| `STAMPEDE_PERSON` | Default person, as `--person` does. |
| `STAMPEDE_PROVIDER` | `anthropic` (default), `openai` or `session`. Setting this, `STAMPEDE_MODEL` or `STAMPEDE_BASE_URL` makes the console ignore the profiles and build its model from these variables. |
| `STAMPEDE_MODEL` | Model id for the environment-built model. |
| `STAMPEDE_BASE_URL` | Server for the environment-built model. A base URL makes it keyless. |
| `STAMPEDE_COMMAND` | CLI for the session provider when set from the environment. Default `claude`. |
| `STAMPEDE_EFFORT` | Effort for the session provider when set from the environment. |
| `STAMPEDE_SYSTEM` | A system prompt. |
| `STAMPEDE_SYSTEM_FILE` | A file holding the system prompt. Wins over `STAMPEDE_SYSTEM`. |

Values in the env file of 8 bytes or more are also protected by the gateway's outbound filter. Store webhook secrets and comment tokens in the vault with `/add-secret NAME=VALUE`, never in this file.


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