> ## Documentation Index
> Fetch the complete documentation index at: https://stampede.autonomousorganizations.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Server install

> Install Stampede on a Linux server from a release binary or with the remote installer, under a dedicated user with a private home.

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](https://stampede.autonomousorganizations.ai/production/security.md)). An administrator creates the user once:

```bash theme={null}
sudo useradd --create-home --shell /bin/bash stampede
sudo apt-get install -y ca-certificates
```

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:

```bash theme={null}
mkdir -p ~/.local/bin ~/stampede-work
export PATH="$HOME/.local/bin:$PATH"
gh release download v0.5.3 --repo OWNER/REPO -p stampede-linux-x86_64 -p SHA256SUMS -D ./release
```

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:

```bash theme={null}
(cd ./release && sha256sum -c SHA256SUMS)
sha256sum ./release/stampede-linux-x86_64
```

Then install it and confirm the version:

```bash theme={null}
install -m 755 ./release/stampede-linux-x86_64 ~/.local/bin/stampede
stampede --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:

```bash theme={null}
stampede init --tools-full-access false --tools-write-path "$HOME/stampede-work"
```

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](https://stampede.autonomousorganizations.ai/production/security.md) 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:

```bash theme={null}
touch ~/.stampede/env && chmod 600 ~/.stampede/env
${EDITOR:-vi} ~/.stampede/env
```

```text theme={null}
ANTHROPIC_API_KEY=...
OPENROUTER_API_KEY=...
```

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](https://stampede.autonomousorganizations.ai/reference/configuration.md#env-file).

### 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:

```bash theme={null}
stampede node init server --listen 100.64.0.10:7443 --advertise 100.64.0.10:7443
```

```bash theme={null}
stampede node init server --listen 127.0.0.1:7443 --advertise 127.0.0.1:7443
```

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

```bash theme={null}
stampede service install
stampede doctor
```

`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](https://stampede.autonomousorganizations.ai/production/services-and-doctor.md) explains each row.

Configure the gateway or webhooks next ([Telegram setup](https://stampede.autonomousorganizations.ai/start/telegram-setup.md), [Webhooks](https://stampede.autonomousorganizations.ai/start/webhooks.md)), 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.

```bash theme={null}
./install.sh --remote stampede@server.example.com --name server --pair-with laptop --policy research
ssh stampede@server.example.com stampede doctor
```

| Flag | Meaning |
| - | - |
| `--name NAME` | Lowercase node name for the machine being installed: 1 to 63 letters, digits or internal `-`. Required. |
| `--remote USER@HOST` | Install over ssh on that machine instead of this one. |
| `--pair-with VALUE` | Pin this machine and the server to each other. `VALUE` is this machine's own node name, or a card file path. Only with `--remote`. |
| `--policy P` | Authority ceiling each side grants the other for unattended requests: `research` (default, read-only), `builder` (bounded changes) or `operator` (unrestricted). |
| `--port N` | UDP port for the node listener. Default 7443. |
| `--listen-ip IP` | Address to bind and advertise. Default: the single address `tailscale ip -4` prints on the machine being installed. None or several stop the install. |

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.

> [!WARNING]
>
> `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:

```bash theme={null}
scripts/build-linux.sh
ls -l dist/stampede-linux-x86_64
```

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.

| Path | Contents | Mode |
| - | - | - |
| `~/.local/bin/stampede` | the binary | 0755 |
| `~/.stampede/` | the home | 0700 |
| `~/.stampede/env` | provider keys and `STAMPEDE_*` settings | 0600 |
| `~/.stampede/config.toml` | profiles, tools, gateway, webhook and node settings; never a key | 0600 |
| `~/.stampede/secrets.enc` | the encrypted secret vault, if used | 0600 |
| `~/.stampede/runtime/` | the encrypted run store and node identity | 0700 |
| `~/.stampede/cards/` | public node cards, yours and pinned peers' | 0700 |
| `~/.stampede/run/` | worker heartbeats and error records | 0700 |
| `~/.stampede/logs/` | one log per worker | 0700 |
| `~/stampede-work/` | the work directory, outside the home | owned by the user |

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.