~/.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,
gitandcurl. - A C compiler for the build: the Xcode command line tools on macOS (
xcode-select --install),build-essentialon Debian or Ubuntu. - An API key for the provider.
- Either Tailscale running on the machine, or the
--listen-ipoption shown below.
Installation
1
Install the Rust toolchain
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
~/.stampede/env in an editor and add one line with the key:4
Run the installer
~/.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.
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
The console
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 theresearch preset, which reads files, has no file-writing tool and runs no program:
@editor is a request to that person. It runs while you keep typing, and the console prints its progress:
@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:
--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
- Concepts: home, person, preset, run, sub-agent and gateway.
- Persons and presets: more persons and what each preset allows.
- Schedules: a task a person runs on a timer.
- Providers: a second provider or a local model.
- Telegram: a bot for a small group.
- Multiple machines: pair this machine with another one.