Skip to main content
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; terms such as home, person and preset are defined in Concepts.

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 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.
  • 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:
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.~/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

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.
Then write the configuration with full access off. A home that serves members runs with 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:
The ranges are in Limits.
4

Create the persons

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:
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:
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.
6

Add the gateway section

Add to ~/.stampede/config.toml, with the service user’s real home path and your own numeric id:
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

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:
/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.
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:
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.
  • 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. Timed work for the same persons is in Scheduled tasks.