Skip to main content
A working installation is one binary in ~/.local/bin, one private directory at ~/.stampede (the home), and a provider key in a file only you can read. This page goes from an empty laptop to a first answer, then to a first person. It uses the Anthropic API; another provider changes only the key and the model profile (Providers).

Prerequisites

  • macOS or Linux, with a terminal, git and curl.
  • A C compiler for the build: the Xcode command line tools on macOS (xcode-select --install), build-essential on Debian or Ubuntu.
  • An API key for the provider.
  • Either Tailscale running on the machine, or the --listen-ip option shown below.
On a Linux x86_64 server you can skip the build and use the release binary instead (see Linux release binary).

Installation

1

Install the Rust toolchain

Open a new terminal afterwards so cargo is on the PATH. The repository pins its compiler version, and rustup installs that version the first time a cargo command runs in the checkout.
2

Clone the repository

OWNER/REPO is the repository you were given. The commands that start with ./ run from this directory.
3

Create the env file

Open ~/.stampede/env in an editor and add one line with the key:
4

Run the installer

Without Tailscale, the script stops and asks for a listen address. On a machine you will not pair with another one, the loopback address is enough:
The script builds the release binary into ~/.local/bin/stampede, writes the default configuration with stampede init, creates the node identity (--name is the lowercase name other machines will use for this one), and installs two background workers: the node and the schedule worker. The first build takes several minutes. Running the script again changes nothing. ~/.local/bin must be on your PATH. The script prints a notice when it is not.

The env file

~/.stampede/env is the only place a key lives. It holds one KEY=value per line: provider keys such as ANTHROPIC_API_KEY or OPENROUTER_API_KEY, and any STAMPEDE_* setting. Every command and every worker loads it once at startup, and a variable already set in your shell wins over the file. The file must be a regular file you own with mode 0600, inside a directory with mode 0700. A symlink, another owner, or any group or world permission stops the command with an error that names the path and the chmod that fixes it.
Write keys into the file with an editor. A key typed on a command line stays in your shell history.

Installation check

stampede doctor prints one row per part of the installation: the configuration, the file modes, one row per model profile, the node and the workers. It exits with status 1 when any row is red, and that row says what is wrong. stampede doctor --offline skips the rows that need the network. See Services and doctor for every row.

First answer

This sends one question and prints one answer, and keeps nothing afterwards. It proves the key and the model profile work.

The console

On a terminal, stampede opens the console: a conversation in which the model can call tools. Start it in the directory you want it to work in, and ask for something that needs a tool:
stampede chat opens the simpler line console instead. To make it the default, set console = "chat" at the top of ~/.stampede/config.toml. The laptop install writes full_access = true under [tools]: in your own console the file tools reach any path and the command tool runs any program, as you would yourself. Set require_approval = true in the same section to have the console ask before every tool call. Both keys are described in Configuration.

First person

A person is a named assistant with a purpose and a policy. Create one with the research preset, which reads files, has no file-writing tool and runs no program:
In the console, a line that starts with @editor is a request to that person. It runs while you keep typing, and the console prints its progress:
A request such as @editor delete README.md cannot delete the file: the person has no tool for it, and any call it tries outside its policy is refused. To see what the person did:
A person created without --policy is free: it may use every tool and run any program.

Headless run

stampede agent runs a task to the end with no console and records every step. Continue an interrupted run with stampede runs resume RUN_ID.

Linux release binary

Releases ship a Linux x86_64 binary, stampede-linux-x86_64, with its sha256 in the release notes. On a Linux server, this replaces the Rust toolchain, the checkout and install.sh:
stampede init creates ~/.stampede with the default model profiles and writes no env file. The background workers, the service user and a Telegram bot are covered in Server install.

Next steps