Skip to main content
A server that runs a Telegram gateway, webhooks or schedules needs Stampede installed once, under its own user, with workers that keep running after you log out. An installation is one binary at ~/.local/bin/stampede, one private directory at ~/.stampede (the home), one node identity, and the supervised workers. There are two ways to get there: install the released Linux binary on the server, or run install.sh --remote from a machine that already has Stampede.

Requirements

  • Linux on x86_64. The release binary is built against glibc 2.36, so it runs on Debian 12, Ubuntu 24.04 and later.
  • systemd with user services. The workers run as systemd user units.
  • The ca-certificates package, so the workers can reach the model providers and the Telegram Bot API.
  • An API key for at least one model provider.
  • For the remote install only: a source checkout and Docker on your local machine, ssh access to the server, and Tailscale on both machines.

Dedicated user

Run Stampede as a user that owns nothing but its home directory and a work directory. Every person’s command runs with that user’s rights, so the user’s reach is the ceiling of what any person can do (see Security model). An administrator creates the user once:
Every step after this runs as that user, never with sudo. Log in as the user directly (for example ssh stampede@host) so systemd starts a user session for it.

Install from a release binary

Each release publishes stampede-linux-x86_64 and a SHA256SUMS file, and its release notes print the sha256 of the binary. Download both into a fresh directory. With the GitHub CLI logged in, replace OWNER/REPO with the repository you were given:
Add the export PATH line to the user’s shell profile as well. The service units use absolute paths and do not depend on it. Check the binary before you install it. The check must print stampede-linux-x86_64: OK, and the sha256 must match the one in the release notes:
Then install it and confirm the version:

Create the home

stampede init creates ~/.stampede with mode 0700, writes the default model profiles to config.toml, and writes an explicit [tools] posture. On a server that serves other people, confine the file tools to the work directory:
A bare stampede init writes full_access = true, which lets the operator’s own runs read and write any path and run any program. That is the laptop default. A home that serves Telegram members or webhooks should use full_access = false (the gateway trust statement in Security model explains why). init never overwrites an existing config.toml. It writes the default profiles only to a file that does not exist yet, and when the file already states a different [tools] posture it stops with nothing written.

Write the env file

~/.stampede/env holds the provider keys, one KEY=value per line. It is the only place key material lives. Create it empty with the right mode, then add the keys with an editor:
Never put a key on a command line, where the shell history keeps it. The other keys this file can hold are listed in the configuration reference.

Create the node identity

Every home runs the node worker, and the node worker does not start without a node identity. Bind it to the server’s tailnet address if the server will pair with another machine, or to loopback if it will not:
The name is lowercase letters, digits and -. The port is UDP. An identity that advertises 0.0.0.0 fails in stampede doctor, because a peer cannot reach a wildcard address.

Start the workers

service install writes one systemd user unit per worker, enables linger for the user so the units keep running with no login session, and starts them. If the host’s policy refuses linger for an ordinary user, an administrator runs sudo loginctl enable-linger stampede once. doctor must exit 0 before you hand the server to anyone. Services and doctor explains each row. Configure the gateway or webhooks next (Telegram setup, Webhooks), then run stampede service install again so it renders the units for the new workers.

Remote install from a source checkout

install.sh --remote installs on a server over ssh without compiling there. It runs from the root of a source checkout, on a machine that is already installed (./install.sh --name NAME on that machine first), and it uses that machine’s ~/.stampede/env for the server.
The script, in order:
  1. Cross-builds the Linux binary in Docker (next section) and copies it to ~/.local/bin/stampede on the server, skipping the copy when the server already has the same bytes.
  2. Runs stampede init --tools-full-access false --tools-write-path "$HOME/stampede-work" on the server, so the file tools there read and write only inside ~/stampede-work.
  3. Copies this machine’s ~/.stampede/env to the server once, as a 0600 file. It never overwrites an env file that is already there, and never prints a key.
  4. Creates the server’s node identity on its own tailnet address and exports its card.
  5. With --pair-with, pins the server to this machine first and this machine to the server last.
  6. Runs stampede service install on the server.
Every step is idempotent. A rerun with the same flags changes nothing and ends with install: nothing to do. A failure stops at that step with no rollback, and the fix is to rerun the same command once the cause is resolved.
full_access = false bounds the file tools only. A program a person may run (git and cargo are on the default list) runs with the login user’s rights outside every configured root.

Docker cross-build

The remote install calls scripts/build-linux.sh, which you can also run on its own:
It builds for Linux x86_64 inside a Rust image pinned by digest, with --locked, so the dependency versions are the ones Cargo.lock names. The image’s glibc 2.36 is older than Ubuntu 24.04’s, so the binary runs there. The script stops when the image’s compiler differs from the version rust-toolchain.toml pins, and when docker is not on the path or the daemon is not reachable. It prints the image digest, the build time and the highest glibc symbol version the binary needs. Two named Docker volumes keep the cargo registry and the build directory between runs, so later builds are incremental.

Home layout and file modes

Every file under ~/.stampede is private to the user. The binary refuses to read a key file, config file or directory that is a symlink, belongs to another user, or has any group or world bit, and the error names the path and the chmod to run. stampede doctor checks these modes on every run. A loose mode is fixed by stampede init, which tightens it; a symlink, another owner or a group or world write bit is refused without reading, and you fix it by hand. Keep the work directory outside ~/.stampede. The gateway refuses a workdir inside the home or one that contains it.