Skip to main content
The gateway lets a small group of people reach the persons of one Stampede home from a Telegram bot. A member writes to the bot in a private chat or in a group you listed, names a person and states a request. The person runs it on the home under its own standing policy, and the answer comes back as a reply to the message in the same chat. The gateway is one worker, stampede service run gateway, kept running by the operating system’s supervisor like the node and schedule workers. It is configured in [gateway.telegram] in ~/.stampede/config.toml. For a step-by-step setup from an empty host, see Set up a Telegram assistant.

Trust statement

Read this before giving anyone the bot. A member who can reach a person gets what that person’s preset allows, unattended, on the host the worker runs on. Presets are described in Presets.

Who can address whom

  • In a private chat every member can address every person of the home that is not a requester. A requester person is the person that stands for a member; it never runs a model.
  • In a listed group every member can address every person in the group’s persons list, or every non-requester person when the list is empty.
  • There is no per-member person list. A person with the free (operator) preset gives every member who can address it unattended, unrestricted effects on the host.
  • A person a member can address may open a task room and wake other persons of the home, whether or not the member’s chat can address them. Each acts under its own policy, narrowed by what the member’s request carried. The [rooms] limits bound how many runs one room starts (64 by default). See Mail and task rooms.

Groups

  • Everyone in a listed Telegram group reads every answer posted there, configured member or not, and a later joiner of a supergroup can read its history. The group’s membership is the read boundary, and you control it in Telegram.
  • Persons are addressed by a leading @name, so a person should not share its name with a human in the group.
  • A person’s memory and skills span chats: something learned in one member’s private request can surface in a group answer.
  • A group’s persons list limits who its members address. A listed person may still ask any helper within the hop cap, and the helper’s answer reaches the group through it.
  • A group upgraded to a supergroup gets a new chat id, and the old entry then matches nothing.
  • The supported group setup is privacy mode off. In BotFather run /setjoingroups (on) and /setprivacy (off), then remove the bot from the group and add it again. With privacy on, ordinary @person requests are not delivered reliably. The host keeps a message’s text only when it is a command or a request to a person reachable from that chat; unaddressed chatter leaves only its update id in the log.

What persons can reach

  • full_access = false limits the file and config tools only. It does not limit what a preset’s command tool runs.
  • A free person runs any program on every home, and so does a maintainer. A builder’s command tool runs cat, head, cargo and git, which read any file of the service user, the env file and the bot token included, and a repository’s own build runs whatever the repository says. Any preset whose list holds an interpreter (node, npx, npm, python3, make, go, cargo) reaches as far. Only the research preset has no command tool.
  • A request to a builder person runs its whole program list, gh included, with the service user’s rights. Such a person can print a git host login stored for the service user with gh auth token, and the outbound filter does not know that value. Store such a login only if its disclosure to members is acceptable.
  • With full_access = true, a gateway-started run of a free person, or its sub-agent, can write config.toml, the member list included. A home that serves members sets full_access = false.
  • A person that writes files (writer, builder, maintainer, free) can be asked to edit AGENTS.md, CLAUDE.md or STAMPEDE.md in the work directory, and every later run there loads the edit, other members’ requests included. Set project_instructions = false for the home or the person where that is not acceptable. See Project instructions.
  • A person whose preset runs commands runs as the service user and can edit config.toml or signal the worker. The worker reloads the member and group lists after every poll, so such an edit applies within one poll.
  • Per request: one run per hop and a root hop cap of 3 (a person may ask a helper, which may ask one more), each run bounded by its own turn_model_calls and timeout. There is no aggregate budget per member request beyond the “not finished in time” bound below.
  • Those bounds meter model calls only. A program a person runs spends through any credential the service user can read, outside every ledger. A gateway that exposes command tools needs provider-side hard quotas or spend-limited credentials; without them, give members research persons only.
  • The run journal records what commands printed. The outbound filter keeps the token and configured keys out of Telegram, and does not keep them out of the journal.
  • Other members’ run metadata stays visible to a person’s run through the stampede_state views, and to you in stampede runs show, which prints the starting grant of a member’s request.
Give members research persons, or accept the above. Run the worker as a dedicated OS user that owns nothing but the home and the work directory. stampede doctor’s gateway row lists the persons that run programs (free, maintainer, builder, reviewer, or a custom list with run_command) by name and preset label; stampede person show NAME lists the allowed commands. More hardening advice is in Security.

Configuration

The model-facing config tools refuse to write [gateway]. Unknown keys are refused at load.

Mapping members to persons

Each member is mapped to one requester person. A requester never runs a model; it is the address a working person replies to. It must be a person that has never run, and main cannot be one. To add a member:
1

The member sends /start

The new member opens a private chat with the bot and sends /start. The bot does not answer a non-member; the account is recorded as a pending sender.
2

Find the id

On the host, list pending senders:
It prints each Telegram id, when it was first and last seen, how many times, and the first name Telegram reported. The numeric id is the identity. The name, times and count are chosen by the sender and prove nothing, so confirm the id with the member over a channel you already trust.
3

Add the member

A person that does not exist yet is created as a research requester (purpose “A team member writing from chat” unless you pass --purpose TEXT). An existing person is used only if it has never run. The command writes the member table to config.toml and removes the id from the pending list. A duplicate id or person, main, or a person listed in a group is refused and nothing is created.
No restart is needed: the running worker serves the new member after its current poll, or at once after stampede service reload. stampede gateway pending clear [ID] drops one pending sender, or all of them. Pending senders are personal data you hold: at most 100 are kept, oldest dropped first. None of the three gateway commands can be run from inside a run. To revoke a member or group, edit [gateway.telegram] (remove or remap the member, remove the group or narrow its persons list). The worker applies the change after its current poll, or at once on stampede service reload. Open requests of that account or group end with no line, a running one is cancelled, and helper mail not yet claimed is cancelled too.

What a member can do

A text message from a configured member reaches the worker in the member’s private chat or in a listed group. Messages in other groups, from non-members, from bots, from channels or anonymous admins, edits and media are dropped and never answered. In a group the text may start with the bot’s @username, which is removed before routing, and a command may carry the bot’s suffix (/who@yourbot). An unaddressed group message is served only when it is a known command or a request to a person the group can reach; anything else stays silent. In a group with a persons list, a request to a person outside it gets “That person is not available in this chat. /who lists who is.” There are no live progress edits. The receipt is the only sign a request is running; /status shows it and /cancel ID ends it. A message sent while the worker is down is picked up once when it starts.

Answers and terminal lines

A person working for a member reaches the member by sending a message to the member’s requester person. A run’s final text is also sent back to whoever asked, unless the run already sent that requester a message of its own. Forwarded text is a reply to the original message, split at 4096 UTF-16 units without cutting a character. When a person answers with a task room, the request has one answer, the room’s summary, forwarded when the room closes. The request stays open until then, and other requests to the same person wait in the queue. Use a second coordinator person for concurrent work. A request ends when its run and every helper it asked are done. The member then gets at most one terminal line: The handoff summary is what a capped run’s reserved last model call wrote: what was done, what was not, and what should happen next. The words match the stop: line of stampede runs show. “Not finished in time” means the request has been open longer than four turn timeouts plus five minutes, at most an hour. The turn timeout is the longest any configured profile allows. A line whose send failed is sent again on the next pass, prefixed “Recovered after a restart; this may repeat an earlier message.” A member who blocked the bot gets no retries. A Telegram 429 holds every send for the wait Telegram names, at most 300 seconds. A request cut off by a worker restart settles as interrupted at the next start; nothing is replayed.

Conversation context

Each request carries the earlier requests and answers of its chat with the same person, so a member can answer a question the person asked or say “the same for about.html”. The person sees them as one block ahead of the request, marked as untrusted user text.
  • The window is the last 6 answered requests whose latest answer was sent within 24 hours: in a private chat those of the same member, in a group those of every member of that group.
  • A private exchange never reaches a group, and a group’s never reaches a private chat.
  • A request sent as a Telegram reply to an earlier answer also carries that pair, at any age.
  • Each request or answer is cut at 2,000 bytes, all of them together at 12,000.
  • The answer kept is the text the member was sent, after the outbound filter. No approval, grant, open question or file carries over.
/new ends the window for that chat. The request texts stay in the store.

Questions

The run working on a member’s request may ask that member a question when it cannot go on without a decision. Only the root run asks, and only the member who sent the request. Helpers, sub-agents and scheduled or mailbox runs cannot ask, and a call reads {"status":"no_operator"}. A run may ask up to four questions in one call. The member gets them one at a time, each as a reply to the request, with a short header, the question and numbered options when there are any. The member answers by replying with a number (2, or 1,3 when several may be chosen) or their own words.
  • In a private chat a plain message that is neither a command nor an @person request also answers the open question.
  • In a group only a reply to the question’s message counts, and only from the member who asked.
  • A message starting with @person is always a new request, and a command is always a command. /cancel closes the question with the request.
A question waits at most 30 minutes, less when the run’s own time limit is nearer. Without an answer the member gets “No answer received; continuing without it.” and the run goes on. A restart ends every open question, and the request ends as interrupted. While a question waits, its run holds the home’s one person slot, so requests to other persons wait with it.

Outbound filter

Every text the worker sends is checked over its whole length before it is split, against:
  • the bot token,
  • the value of every key variable a model profile names (or the provider’s default variable), resolved from the environment and then the unlocked secret vault,
  • every other value in the env file that is 8 bytes or longer.
A text that contains one is replaced by “The reply was withheld: it contained a value this host keeps private.” and the request settles failed. The log carries the update id only. The filter is an exact substring check. A value a person re-encodes, splits or paraphrases goes through, so the filter is a layer behind the preset choice. A configured value that is itself part of a fixed line the worker sends is refused at startup, naming the line and never the value; stampede doctor reports the same.

Telegram formatting

Forwarded replies, questions and stop lines that carry a summary are model text. Their Markdown is rendered as Telegram HTML:
  • bold and italic,
  • inline code and fenced code blocks,
  • http and https links,
  • headings (as bold) and list bullets.
Everything else is escaped and shown as written. The outbound filter runs before the rendering. A part Telegram refuses for its markup is sent once more as plain text. Fixed lines are always plain.

Sizing a long builder run

A builder person’s request is one run, each turn bounded by turn_model_calls under [tools]. Two calls are kept for closing the turn, so the default 26 gives 24 tool rounds. Set it, between 2 and 100, from the longest build or test cycle the person needs, and the profile timeout from the longest single command. See Limits.

Operations

  • stampede doctor has a gateway row: not configured, or the member, group and pending-sender counts, the work directory, the persons that run programs, and a failure when a configured value is part of a fixed line. Ids and names never appear. A green row does not prove the token; a wrong one shows as getMe failed (unauthorized) in the log.
  • stampede service install renders the gateway unit only when [gateway.telegram] is configured. See Services and doctor.
  • The worker needs the host’s CA bundle (ca-certificates on Debian and Ubuntu). Without it every poll fails with the tls kind.
  • The member list and the group list reload after every poll and at once on stampede service reload. New content is checked as at start. A refused edit keeps the old lists and logs gateway: reload refused: ...; an applied one logs gateway: reload applied: N member(s), M group(s).
  • token_env, workdir, requests_per_hour and api_base need stampede service restart. A change logs gateway: restart required for KEY and is ignored until then. The token, the env file and the model profiles are never re-read by a running worker.
  • service stop and service restart act on the installed worker only. A gateway started by hand with stampede service run gateway must be stopped by hand.
  • The log carries update ids, sequences, kinds and fixed sentences, never a message body, a URL or the token.

A leaked bot token

Revoke it with BotFather. It stops working at once, and the worker logs getMe failed (unauthorized). Put the new token in ~/.stampede/env and run stampede service restart gateway. Rotating the same bot’s token keeps its rows. Replacing the bot with a different one settles the old bot’s open requests as failed at the next start, so let open requests finish first when that matters.