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

# Getting started

> Install Stampede on macOS or Linux, get a first answer from the model, and create a first person.

A working installation is one binary in `~/.local/bin`, one private directory at `~/.stampede` (the [home](https://stampede.autonomousorganizations.ai/concepts.md#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](https://stampede.autonomousorganizations.ai/models/providers.md)).

## 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](#linux-release-binary)).

## Installation

**1. Install the Rust toolchain**

```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

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**

```bash theme={null}
git clone https://github.com/OWNER/REPO.git stampede
cd stampede
```

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

**3. Create the env file**

```bash theme={null}
mkdir -m 700 ~/.stampede
touch ~/.stampede/env && chmod 600 ~/.stampede/env
```

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

```text theme={null}
ANTHROPIC_API_KEY=sk-ant-...
```

**4. Run the installer**

```bash theme={null}
./install.sh --name laptop
```

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:

```bash theme={null}
./install.sh --name laptop --listen-ip 127.0.0.1
```

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.

> [!WARNING]
>
> Write keys into the file with an editor. A key typed on a command line stays in your shell history.

## Installation check

```bash theme={null}
stampede --version
stampede doctor
```

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

## First answer

```bash theme={null}
stampede -prompt "What is the capital of France"
```

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

## The console

```bash theme={null}
cd ~/some-project
stampede
```

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:

```text theme={null}
list the files here and say in two sentences what this project is
```

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

## First person

A [person](https://stampede.autonomousorganizations.ai/concepts.md#person) is a named assistant with a purpose and a policy. Create one with the `research` [preset](https://stampede.autonomousorganizations.ai/concepts.md#preset), which reads files, has no file-writing tool and runs no program:

```bash theme={null}
stampede person create editor --purpose "Reviews prose for clarity; never edits files" --policy research
stampede person list
```

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:

```text theme={null}
@editor review README.md for clarity and list three improvements
```

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:

```bash theme={null}
stampede person runs editor
stampede runs show RUN_ID
```

A person created without `--policy` is free: it may use every tool and run any program.

## Headless run

```bash theme={null}
stampede agent "inspect the project, run its tests, and summarize failures"
stampede runs list
```

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

```bash theme={null}
mkdir -p ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"
gh release download v0.5.3 --repo OWNER/REPO -p stampede-linux-x86_64 -D ./release
sha256sum ./release/stampede-linux-x86_64     # must equal the sha256 in the release notes
install -m 755 ./release/stampede-linux-x86_64 ~/.local/bin/stampede
stampede --version
stampede init
touch ~/.stampede/env && chmod 600 ~/.stampede/env   # then add the key with an editor
stampede -prompt "What is the capital of France"
```

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

## Next steps

* [Concepts](https://stampede.autonomousorganizations.ai/concepts.md): home, person, preset, run, sub-agent and gateway.
* [Persons](https://stampede.autonomousorganizations.ai/persons/overview.md) and [presets](https://stampede.autonomousorganizations.ai/persons/presets.md): more persons and what each preset allows.
* [Schedules](https://stampede.autonomousorganizations.ai/start/schedules.md): a task a person runs on a timer.
* [Providers](https://stampede.autonomousorganizations.ai/models/providers.md): a second provider or a local model.
* [Telegram](https://stampede.autonomousorganizations.ai/start/telegram.md): a bot for a small group.
* [Multiple machines](https://stampede.autonomousorganizations.ai/teamwork/multiple-machines.md): pair this machine with another one.


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