Skip to main content
Schedules, Telegram, webhooks and requests from paired machines are served by long-running workers, so they must keep running after you close the terminal and come back after a reboot or a crash. stampede service hands the workers to the operating system’s supervisor, and stampede doctor tells you whether the whole installation is healthy.

Workers

Each worker is the same binary started as stampede service run WORKER. A worker loads ~/.stampede/env and config.toml itself when it starts.

Service commands

start, stop, restart and uninstall act on one worker when you name it, and on every installed worker when you do not. WORKER is node, schedule, gateway or webhook. install is the command to rerun after an upgrade or after adding a gateway or webhook section. It leaves an identical unit alone, rewrites a unit it generated when the binary moved or the version changed, and refuses a unit it did not generate or that was edited since, naming the file. It prints service: nothing to do when nothing changed. start and restart wait up to 35 seconds for the worker’s first heartbeat before reporting success. reload applies only to the gateway. It makes the running gateway re-read the member and group lists without a restart. Any other change to config.toml or the env file takes effect at the next restart. uninstall --orphans removes registrations left by an installation whose home no longer exists. Deleting ~/.stampede without service uninstall first leaves the supervisor retrying a binary or home that is gone; --dry-run lists what would be removed.

Supervisors

Units are named stampede-WORKER-TAG, where the tag is derived from the home, so two users on one host never collide. A unit runs the installed binary by absolute path, sets only HOME, and carries no credentials. On Linux, install also enables linger for the user so the units keep running with no login session; loginctl disable-linger reverts it.

Status

stampede service status prints one line per worker and exits 0 only when every installed worker is running.

Logs and heartbeats

Logs carry fixed sentences, ids and kinds. They never carry keys or the bot token.

stampede doctor

doctor checks the installation and prints one row per check: a status, a label and a detail. It is read-only: it creates, repairs and migrates nothing. It exits 1 when any row is FAIL, and evaluates every row first, so you see every problem in one run. Rows never contain provider responses, keys, base URLs or file contents, so the output is safe to paste into a support request. The last line summarises the rows: doctor: all rows green only when nothing failed, warned or was skipped; otherwise doctor: N red, with the counts of unavailable, skipped and warned rows. --offline skips every row that needs the network (model transports, MCP server probes and peers) and shows them as skipped.

Rows

Common fixes

A green gateway row checks the configuration and paths only. It never calls the Telegram Bot API, so a wrong but well-formed token shows up as getMe failed (unauthorized) in ~/.stampede/logs/gateway.log. Send a private /start from an allowed account before you hand the bot to anyone.
doctor reads the env file and environment of its own invocation. It does not prove that a running worker loaded the same values, so restart the workers after editing either.