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 bothanalyst and site. The two presets differ in kind:
analysthas the research preset. It reads files inside the work directory and runs no program.sitehas the builder preset. It writes files in the work directory and runsgit,gh,npm,cargoand 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.
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-certificatespackage. 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 withsudo. - 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
~/.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.full_access = false:3
Raise the turn budget
If The ranges are in Limits.
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:4
Create the persons
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 For Remove
analyst answers from under the work directory: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: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 The section needs at least one member.
~/.stampede/config.toml, with the service user’s real home path and your own numeric id: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 statusandstampede doctorare 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 needsstampede 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.