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

# Concepts

> The six terms the rest of the documentation uses: home, person, preset, run, sub-agent and gateway.

Six terms carry the rest of the documentation: home, person, preset, run, sub-agent and gateway. Each section defines one and shows one example, with a link to the page that covers it in full.

## Home

A home is the private directory `~/.stampede` of one operating-system user. It holds the configuration (`config.toml`), the env file with the provider keys (`env`), the encrypted store of runs, persons and mail, the node identity, and the workers' logs. Every `stampede` command and every worker of that user reads the same home, so the persons, schedules and runs of one home form one installation. The home is found through `HOME`, so another user account has its own.

The directory has mode `0700` and the files in it `0600`. A looser mode on the env file is a startup error that names the path and the `chmod` to run.

Create a home with the default model profiles, then list its parts and their health, one row each:

```bash theme={null}
stampede init
stampede doctor
```

More: [Getting started](https://stampede.autonomousorganizations.ai/quickstart.md), [Configuration](https://stampede.autonomousorganizations.ai/reference/configuration.md).

## Person

A person is a named assistant that lives in a home: a name, a purpose, an optional private identity text, a model profile and a standing policy. A person keeps its own memory, goals and mail between runs. You create several persons to have specialists you address by name. They can message each other, run on a schedule, and take requests from a paired machine, a Telegram bot or a webhook. Work that needs several of them runs as a task room: the person you asked coordinates, the others are woken through their mail, and you get one summary.

Persons cooperate under one user account. They are separate identities inside Stampede, and they share the operating-system user's rights. A fresh home has one person, `main`.

Create a person that reviews prose, then address it from the console (`stampede`) by starting a line with its name:

```bash theme={null}
stampede person create editor --purpose "Reviews prose for clarity; never edits files" --policy research
```

```text theme={null}
@editor review README.md for clarity and list three improvements
```

More: [Persons](https://stampede.autonomousorganizations.ai/persons/overview.md), [Mail and task rooms](https://stampede.autonomousorganizations.ai/teamwork/mail-and-task-rooms.md).

## Preset

A preset is a named policy: the list of tools a person may call and the list of programs it may run when nobody is watching, as in a request from another person, a schedule fire, a gateway request, a webhook delivery or work from a paired machine.

| Preset | What it allows |
| - | - |
| `research` | Reads files. Runs no program. |
| `writer` | `research` plus the file-writing tools. |
| `reviewer` | `research` plus the command tools, with a list of test and build programs. |
| `coordinator` | `research` plus scheduling and questions to the operator. |
| `builder` | Writes files and runs a list of build and git programs. |
| `maintainer` | The tools of `builder`, and runs any program. |
| `free` | Every tool and any program. `operator` is the same policy. |

A person created without `--policy` is `free`.

A program a preset allows runs with the rights of the user account. A preset bounds which programs start and which paths the file tools reach. It does not bound what a started program reads or writes.

Give a person the `builder` preset, extend it by one program, and print the resulting lists:

```bash theme={null}
stampede person create builder --purpose "Implements small changes in the workspace" --policy builder
stampede person policy builder builder --allow-command make
stampede person show builder
```

More: [Presets](https://stampede.autonomousorganizations.ai/persons/presets.md).

## Run

A run is one piece of work by a model: the request, the model calls and tool calls made for it, and a final status. A console turn, a `stampede agent` command, a request to a person, a schedule fire, a gateway request and a webhook delivery are each a run.

A run is written to the home's journal before each model call and each tool call, so a crash leaves a record of what finished. A tool call whose effect may have happened without being recorded as finished stops the run with the status unknown, and the call is never repeated silently.

A run is bounded by the number of model calls in a turn (`turn_model_calls`, default 26), by the input tokens a turn sends (`turn_input_tokens`, default 500,000) and by the model profile's time limit. A run that reaches a bound ends with a handoff summary of what was done, what was not, and what should happen next.

Start a headless run, list the runs of the home, and print one run's record. The record shows each tool call and its outcome; prompts, arguments and outputs stay encrypted.

```bash theme={null}
stampede agent "inspect the project, run its tests, and summarize failures"
stampede runs list
stampede runs show RUN_ID
```

More: [Limits](https://stampede.autonomousorganizations.ai/models/limits.md), [CLI reference](https://stampede.autonomousorganizations.ai/reference/cli.md).

## Sub-agent

A sub-agent is a child run. A run starts one with the `run_subagent` tool, or several at once with `run_subagents`, to hand over a bounded subtask and get a report back. The child has its own record in the journal, linked to its parent, and its own share of the budget. A person's sub-agent has the person's rights and can do nothing the person could not. A subtask that declares `read_paths` or `write_paths` narrows the child's file tools to those paths.

A prompt that asks for two sub-agents, each given one file:

```text theme={null}
Use run_subagents to run these two independent subtasks in parallel, do not do them yourself: (1) create alpha.txt containing exactly ALPHA; (2) create beta.txt containing exactly BETA. When both reports are back, answer with one line per subtask: label, status, model.
```

More: [Sub-agents](https://stampede.autonomousorganizations.ai/teamwork/sub-agents.md).

## Gateway

The gateway is a worker that connects one home to a Telegram bot. A member of a small group writes to the bot, names a person and states a request. The person runs it on the host under its own preset, and the answer comes back as a reply in the same chat. Each member is listed in `config.toml` by numeric Telegram id, with a person that stands for the member. An account that is not listed gets no answer.

A member who can reach a person gets what that person's preset allows, unattended, on the host. Read the trust statement in [Telegram](https://stampede.autonomousorganizations.ai/start/telegram.md) before giving anyone the bot.

A member's message to a person named `analyst`, and the bot's receipt. The person's answer follows as a reply to the member's message.

```text theme={null}
@analyst how many rows does data/orders.csv have?

Received; working on it.
```

The webhook worker is the equivalent entry point for events from GitHub, GitLab, Linear or a generic sender: each verified delivery on a route becomes one run of the route's person.

More: [Telegram](https://stampede.autonomousorganizations.ai/start/telegram.md), [Telegram setup](https://stampede.autonomousorganizations.ai/start/telegram-setup.md), [Webhooks](https://stampede.autonomousorganizations.ai/start/webhooks.md).


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