The home is private
All state lives in~/.stampede (the home) of one operating-system user: configuration, keys, the encrypted store of runs, persons and mail, the node identity and the logs. The home is mode 0700 and every file in it 0600. Every command and every worker refuses to read a key file, the configuration or the home itself when it is a symlink, belongs to another user, or has any group or world bit, and names the path and the chmod that fixes it. stampede doctor checks the modes on every run.
These modes protect the home from other users on the host. They do not protect it from programs running as the same user, and every program a person runs does run as that user. Run Stampede as a dedicated user that owns nothing but its home and a work directory (Server install).
Stampede requires Unix. It refuses to start on platforms where it cannot enforce owner-only modes.
Where keys live
Keys are never written toconfig.toml. A model profile names the variable that holds its key (key_env = "ANTHROPIC_API_KEY"), and the value comes from one of two places:
- The env file,
~/.stampede/env, mode 0600. It holds oneKEY=valueper line and is loaded once at startup by every command and worker. A variable already set in the real environment wins. - The encrypted vault,
~/.stampede/secrets.enc. Its passphrase isSTAMPEDE_SECRET_KEYin the env file. The passphrase is stretched with Argon2id and each value is sealed with ChaCha20-Poly1305. Names are stored in clear, values never are.
key_env name resolves from the environment first, then from the vault. Manage the vault from the console; listing shows names only and no command echoes a value:
token_env.
Commands and MCP servers start with a cleared environment (PATH, HOME, LANG, LC_ALL, TMPDIR, USER, TERM), plus an MCP server’s own env_passthrough names. A key in the env file therefore does not reach git, gh or a build script through the environment. It is still a file the service user can read.
Presets are the permission boundary
A person’s policy says which tools it may call and which programs it may run when no operator is watching: a gateway request, a webhook delivery, a schedule fire, mail from another person, a request from a paired machine. A preset is a named policy. Presets lists the tools and programs of each.
The program list is the control. A program a preset allows runs with the full rights of the service user, wherever it starts, and can read or write any path that user can reach.
git, cargo, npm, node and python3 run project code, so a preset with any of them reaches as far as the user does: the env file, the vault passphrase, a stored gh login. Only research, writer and coordinator start no program.
[tools] full_access, read_paths and write_paths bound Stampede’s own file tools. With full_access = false the file tools read and write only inside the configured roots, and a root at or above ~/.stampede grants nothing inside it. These settings do not bound what an allowed program does.
A bounded person runs exactly the programs in its list, on every home. A maintainer and a free person run any program on every home. A person created without --policy is free.
Sub-agents inherit the person’s rights
Every person may start sub-agents (run_subagent, run_subagents). A person’s sub-agent has the person’s rights: the same program list, the same MCP tools and the same file roots, and it decides each call through the person’s policy. It can do nothing the person could not. A sub-agent that declares read_paths or write_paths narrows its file tools to those paths; that does not bound what a program it runs reads or writes.
A sub-agent started from the operator’s own console turn is narrower: it reads where its parent reads, writes only inside a declared scope, and runs no command and no MCP tool.
Telegram gateway
A member who can reach a person gets what that person’s preset allows, unattended, on the host the worker runs on.- In a private chat every member can address every person of the home except requester persons (the persons that stand for members). In a listed group, members address the persons the group’s
personslist names, or every non-requester person when it names none. There is no per-member list. - An addressed person can open a task room and wake other persons, whether or not the member’s chat can address them. Each acts under its own policy, narrowed by what the request carried.
- Everyone in a listed Telegram group reads every answer posted there. The group’s membership is the read boundary, and you control it in Telegram.
- With
full_access = true, a gateway-started run of a free person can writeconfig.toml, the member list included. A home that serves members setsfull_access = false. - A builder person can print a git host login stored for the service user (
gh auth token). Store such a login only if its disclosure to the members is acceptable, and use a short-lived token scoped to the repositories involved. - Commands spend through any credential the service user can read, outside every token ledger. A gateway that exposes command tools needs provider-side spend limits on every such credential.
research persons, or accept the reach above. An account that is not listed in [gateway.telegram] gets no answer; the numeric Telegram id is the identity, so confirm it over a channel you already trust before stampede gateway member add.
Webhooks
A webhook delivery is an unattended run of the route’s person under that person’s policy.- A route on an event anyone can cause, such as
issues.openedon a public repository, lets anyone drive that person’s run with their own text and, withdestination = "comment", read the answer. Prefer events only trusted people can cause, such asissues.labeledwith a label match. - Payload text is data. Only the fields the route names reach the model, cleaned and JSON-encoded under a fixed header that marks them untrusted. Nothing in a payload selects the route, person, destination, template or tools.
- GitLab’s
X-Gitlab-Tokenis a static shared token with no integrity over the body. Anyone who sees one delivery can forge a payload for that route. Keep the public side on TLS. - The listener binds
127.0.0.1:8787by default and speaks plain HTTP. Put it behind a TLS reverse proxy or tunnel that forwards/hooks/*only.
Outbound filter
Every text the gateway sends is checked over its whole length against the bot token, every key a model profile names, and every other env-file value of 8 bytes or more. A webhook comment is checked against every route secret and token, every vault value of 8 bytes or more and the gateway’s values. A match is not sent: a gateway member gets “The reply was withheld: it contained a value this host keeps private.” and a webhook delivery recordsfiltered.
The filter is an exact substring check. A value a person re-encodes, splits or paraphrases goes through, and it does not know a gh login or any secret outside those lists. It is a layer behind the preset choice. The run journal still records what commands printed.
Paired machines
A paired machine’s request runs under the smaller of two limits: the ceiling you set when you pinned the peer (--policy on stampede node peer add) and the addressed person’s own policy. The ceiling is local to each machine and never read from the peer’s card. A peer’s run also gets at most the default turn_model_calls and turn_input_tokens, whatever your configuration raises them to. See Multiple machines.
Runs cannot administer the home
A program started by a run’s tools carries the variableSTAMPEDE_INSIDE_RUN. With it set, the stampede command line refuses every command that changes persons, schedules, nodes, services, configuration or stored state, and the run’s own binary is never started by run_command or start_command. The model-facing configuration tools refuse full_access, require_approval, unattended_delegation, [gateway], [webhook], [rooms] and prices by name.
This is provenance, not a sandbox. A program with the user’s rights can clear the variable or edit ~/.stampede directly. The control remains the program list you give each person.