~/.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, MCP servers, Limits, Telegram setup, Webhooks.
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 initwrites 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).
Top-level keys
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.
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.
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.
A transport table also accepts
context_window_tokens, stream_terminal_profile, retry_policy, failover_compatibility, cache_ttl and observation_masking.
retry_policy
All four keys are required when the table is present.[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.
Defaults written by init
[[mcp]]
One table per MCP server. Its tools join the model’s set, prefixed with the label (github__search).
[node]
[rooms]
Bounds on task rooms. Owner-only.
[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.
[gateway.telegram]
The Telegram gateway. Absent, no gateway worker is installed. The whole [gateway] table is owner-only.
[[gateway.telegram.member]]
At least one, at most 256.
[[gateway.telegram.group]]
Optional, at most 64. Absent, the bot serves private chats only.
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.
[[webhook.route]]
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.
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.