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

# Security model

> What protects a Stampede home: private file modes, where keys live, presets as the permission boundary, and what Telegram members and webhook senders can reach.

Stampede runs models that call tools on your machine, and some of that work starts from people or services you do not control: Telegram members, webhook senders, paired machines. Before you open a home to any of them, you need to know which boundaries Stampede enforces and which it leaves to the operating system and to your choice of preset.

## 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](https://stampede.autonomousorganizations.ai/production/server-install.md)).

Stampede requires Unix. It refuses to start on platforms where it cannot enforce owner-only modes.

## Where keys live

Keys are never written to `config.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 one `KEY=value` per 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 is `STAMPEDE_SECRET_KEY` in 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.

A `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:

```text theme={null}
/add-secret OPENROUTER_API_KEY=sk-or-...
/secrets
/rm-secret OPENROUTER_API_KEY
```

Webhook route secrets and comment tokens must live in the vault. The Telegram bot token must live in the env file or the worker's environment, named by `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](https://stampede.autonomousorganizations.ai/persons/presets.md) lists the tools and programs of each.

| Preset | Runs programs | Writes files |
| - | - | - |
| `research` | none | no |
| `writer` | none | yes |
| `coordinator` | none | no |
| `reviewer` | a list of test and build programs | no |
| `builder` | a list of build and git programs, `gh` and `glab` included | yes |
| `maintainer` | any program | yes |
| free (no `--policy`) | any program | yes |

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 `persons` list 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 write `config.toml`, the member list included. A home that serves members sets `full_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.

Give members `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.opened` on a public repository, lets anyone drive that person's run with their own text and, with `destination = "comment"`, read the answer. Prefer events only trusted people can cause, such as `issues.labeled` with 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-Token` is 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:8787` by default and speaks plain HTTP. Put it behind a TLS reverse proxy or tunnel that forwards `/hooks/*` only.

> [!WARNING]
>
> Never name a free, operator or maintainer person on a route that faces the outside. Since 0.5.3 the worker disables such a route at start and re-checks the person before each run, and `stampede doctor` shows it as `FAIL`. A reviewer or builder person is accepted with a `WARN`, because it can start programs with the service user's rights. Create route persons with `stampede person create NAME --policy research`.

## 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 records `filtered`.

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](https://stampede.autonomousorganizations.ai/teamwork/multiple-machines.md).

## Runs cannot administer the home

A program started by a run's tools carries the variable `STAMPEDE_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.


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