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

# Set up a Telegram assistant

> From an empty Linux host to a Telegram bot that reaches a read-only data person and a builder person.

This walkthrough starts from an empty Linux host and ends with a Telegram bot that a small group can write to. The bot reaches two persons: `analyst`, which answers questions from files and changes nothing, and `site`, which edits a repository, runs its build and opens a pull request. The full description of the gateway is in [Telegram gateway](https://stampede.autonomousorganizations.ai/start/telegram.md); terms such as home, person and preset are defined in [Concepts](https://stampede.autonomousorganizations.ai/concepts.md).

## What members get

A member who can reach a person gets what that person's preset allows, unattended, on the host. Every member can address every person of the home that does not stand for a member, so every member of this bot can ask both `analyst` and `site`. The two presets differ in kind:

* `analyst` has the research preset. It reads files inside the work directory and runs no program.
* `site` has the builder preset. It writes files in the work directory and runs `git`, `gh`, `npm`, `cargo` and the other programs of its list with the rights of the host's service user. Those programs can read every file that user can read, the env file with the bot token and the model key included, and a repository's build runs whatever the repository says.

For that reason the host runs Stampede as a dedicated user that owns nothing but its home and the work directory, the model key has a spend limit set at the provider, and the git host token is limited to the repositories `site` works on. If that is more than the group should have, leave `site` out; the rest of the walkthrough works with `analyst` alone. Read the [trust statement](https://stampede.autonomousorganizations.ai/start/telegram.md#trust-statement) before giving anyone the bot.

## Requirements

* A Linux x86\_64 host with glibc 2.34 or newer and the `ca-certificates` package. Each release is checked on Ubuntu 24.04.
* A dedicated service user, created once by an administrator, for example `sudo useradd --create-home --shell /bin/bash stampede`. Every later step runs as that user, never with `sudo`.
* A bot token from BotFather in Telegram (`/newbot`). Use a new bot, never one that already serves something else.
* An API key for the model provider. The steps use the Anthropic API; other providers are covered in [Providers](https://stampede.autonomousorganizations.ai/models/providers.md).
* Your own numeric Telegram user id, read from a Telegram client or an id bot. It is a number, not a username.
* For `site`: a fine-grained token for the git host, limited to the repository it will work on.

**1. Install the binary**

As the service user, download the released binary and check it against the sha256 line in the release notes of the tag. The release notes carry the exact commands for their version; this is the shape:

```bash theme={null}
mkdir -p ~/.local/bin ~/stampede-work
export PATH="$HOME/.local/bin:$PATH"
gh release download TAG --repo OWNER/REPO -p stampede-linux-x86_64 -D ./release
sha256sum ./release/stampede-linux-x86_64
install -m 755 ./release/stampede-linux-x86_64 ~/.local/bin/stampede
stampede --version
```

`OWNER/REPO` is the release repository you were given. Put the `export PATH` line in the service user's shell profile too. Without `gh` on the host, copy the file from a machine that has it. More detail is in [Server install](https://stampede.autonomousorganizations.ai/production/server-install.md).

`~/stampede-work` is the work directory: the directory granted to the persons' file tools. A program a person may run keeps the service user's rights on the whole host, as described above.

**2. Create the home and the keys**

```bash theme={null}
mkdir -m 700 ~/.stampede
touch ~/.stampede/env && chmod 600 ~/.stampede/env
```

Open `~/.stampede/env` in an editor and write two lines, the bot token and the model key. A key never goes on a command line, where the shell history would keep it.

```text theme={null}
TELEGRAM_BOT_TOKEN=...
ANTHROPIC_API_KEY=...
```

Then write the configuration with full access off. A home that serves members runs with `full_access = false`:

```bash theme={null}
stampede init --tools-full-access false
```

**3. Raise the turn budget**

If `site` will work on a repository with a real build, add the two budget keys to the `[tools]` section that `init` wrote in `~/.stampede/config.toml`, so that it reads as below. The defaults (26 model calls and 500,000 input tokens per turn) end a long build early:

```toml theme={null}
[tools]
full_access = false
turn_model_calls = 60
turn_input_tokens = 2000000
```

The ranges are in [Limits](https://stampede.autonomousorganizations.ai/models/limits.md).

**4. Create the persons**

```bash theme={null}
stampede person create analyst --purpose "Answers questions from the files under data/; changes nothing" --policy research
stampede person create site --purpose "Makes small changes in the repository under site/ and opens a pull request" --policy builder
stampede person create alice --purpose "A team member writing from chat" --policy research
```

The first two do the work. The third, `alice`, stands for you as a member: each member has one such requester person, it never runs a model, and it must be a person that has never run. Name it after the member.

Always pass `--policy`. A person created without it is free and may run any program.

**5. Add the data and the repository**

Put the files `analyst` answers from under the work directory:

```bash theme={null}
mkdir -p ~/stampede-work/data
cp orders.csv ~/stampede-work/data/
```

For `site`, log the service user in to the git host with the tool's own login (the token on standard input), set the commit identity, and clone the repository into the work directory:

```bash theme={null}
gh auth login --with-token < token-file
gh auth setup-git
git config --global user.name "Builder"
git config --global user.email "builder@example.com"
git clone https://github.com/acme/website.git ~/stampede-work/site
```

Remove `token-file` afterwards. A token in the env file does not reach `gh` or `git`, because commands run with a cleared environment. Every member who can ask `site` can make it print this login, so store one only if that is acceptable.

A person's run loads the instruction files (`AGENTS.md`, `CLAUDE.md`, `STAMPEDE.md`) of the work directory itself, never of a directory below it. To give `site` the rules of the checkout, copy them to `~/stampede-work/CLAUDE.md`, or make the checkout the work directory. See [Project instructions](https://stampede.autonomousorganizations.ai/persons/project-instructions.md).

**6. Add the gateway section**

Add to `~/.stampede/config.toml`, with the service user's real home path and your own numeric id:

```toml theme={null}
[gateway.telegram]
token_env = "TELEGRAM_BOT_TOKEN"
workdir = "/home/stampede/stampede-work"
requests_per_hour = 20

[[gateway.telegram.member]]
telegram_user_id = 111111111
person = "alice"
```

The section needs at least one member. `workdir` is an absolute path; it is the directory every request's run starts in and is granted.

**7. Start the workers**

```bash theme={null}
stampede service install
stampede service status
stampede doctor
```

`service install` installs the workers as systemd user units and enables linger so they run with no login session. On a host whose policy refuses that, an administrator runs `loginctl enable-linger stampede` once.

`doctor` must show the gateway row green; the row also names the persons that run programs, here `site`. A green row does not prove the token, because doctor never calls Telegram. A wrong token shows as `getMe failed (unauthorized)` in `~/.stampede/logs/gateway.log`.

**8. Send the first messages**

Open a private chat with the bot in Telegram and send, one at a time:

```text theme={null}
/who
@analyst how many rows does data/orders.csv have, and what are its columns?
@site in site/, fix the spelling of "recieve" in README.md, run npm test, and open a pull request
```

`/who` lists `analyst` and `site` with their purposes. Each request gets "Received; working on it." and then the person's answer as a reply to your message, with no progress edits in between. `/status` shows your open requests with their ids and `/cancel ID` ends one. One request per person runs at a time, in the order received.

A person may ask you a question when it cannot go on without a decision. Answer by replying to the question with a number or your own words. A question waits at most 30 minutes, less when the run's own time limit is nearer; without an answer the run goes on without one.

A follow-up such as `@analyst and how many of those are from this year?` works, because a request carries the earlier requests and answers of the same chat with the same person. `/new` starts a new conversation.

When a request ends without an answer the bot sends one fixed line that says why, such as `Stopped: budget_exhausted.` followed by the person's summary of what was done and what was not. The full table is in [Answers and terminal lines](https://stampede.autonomousorganizations.ai/start/telegram.md#answers-and-terminal-lines).

**9. Add a second member**

The new member opens a private chat with the bot and sends `/start`. The bot does not answer. On the host:

```bash theme={null}
stampede gateway pending
stampede gateway member add 222222222 bob
```

`gateway pending` lists the account's numeric id. Confirm the id with the member over a channel you already trust; the name shown beside it is chosen by the sender. `gateway member add` adds the member and creates the requester person `bob`.

No restart is needed: the running worker serves the new member from the next message on. To remove a member, delete their table from `config.toml`; the worker applies it after its current poll.

## Keeping it running

* `stampede service status` and `stampede doctor` are the two health checks. The gateway's log is `~/.stampede/logs/gateway.log`; it carries ids and fixed sentences, never a message body or the token.
* A change to the member list is picked up while the worker runs. A change to `token_env`, `workdir`, `requests_per_hour`, the env file or a model profile needs `stampede service restart gateway`.
* To upgrade, download the new release, check its sha256 as in the first step, then follow the upgrade section of its release notes. See [Upgrading](https://stampede.autonomousorganizations.ai/production/upgrading.md).
* A leaked bot token is revoked with BotFather, replaced in the env file, and the gateway worker restarted.

Groups, the outbound filter and the rest of the operations are in [Telegram gateway](https://stampede.autonomousorganizations.ai/start/telegram.md). Timed work for the same persons is in [Scheduled tasks](https://stampede.autonomousorganizations.ai/start/schedules.md).


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