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

# Upgrading

> Upgrade a Stampede installation to a new release, back up the home before a schema step, and roll back.

An upgrade replaces one binary and keeps everything under `~/.stampede`. Most releases need nothing else, but some move the store to a new schema at first start, and that step is one way: the older binary then refuses the store as newer than itself. The procedure below works for every release and makes the way back explicit.

## Procedure

Run every step as the service user, with no request running. Read the release's entry in the [release notes](https://stampede.autonomousorganizations.ai/reference/release-notes.md) first for its behaviour changes.

**1. Download and verify**

Download the new `stampede-linux-x86_64` and `SHA256SUMS` into a fresh directory, and compare the sha256 with the value in the release notes:

```bash theme={null}
gh release download v0.5.3 --repo OWNER/REPO -p stampede-linux-x86_64 -p SHA256SUMS -D ./release
(cd ./release && sha256sum -c SHA256SUMS)
sha256sum ./release/stampede-linux-x86_64
```

Do not continue unless the check prints `stampede-linux-x86_64: OK` and the sha256 matches the release notes.

**2. Stop the workers**

```bash theme={null}
stampede service stop
```

Stopping first means no old worker picks up the new binary halfway, and no schedule fire or webhook delivery starts while you edit the configuration.

**3. Keep the old binary and back up the home**

```bash theme={null}
cp ~/.local/bin/stampede ~/stampede-previous
cp -a ~/.stampede ~/.stampede-before-upgrade && chmod -R go-rwx ~/.stampede-before-upgrade
```

The copy holds the store, its keys, the vault and the env file. Keep it private (directories 0700, files 0600) and delete it once the new version has run well. The backup is required before a release that moves the schema, and cheap insurance before any other.

**4. Install the new binary**

```bash theme={null}
install -m 755 ./release/stampede-linux-x86_64 ~/.local/bin/stampede
stampede --version
```

If the release adds a configuration key you want, add it now. An older binary refuses a `config.toml` that holds a key it does not know, so add new keys only after the new binary is installed.

**5. Reinstall the units**

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

`service install` rewrites the units for the new version and starts the workers. A plain `restart` keeps the old unit files. Every worker should show `running`.

**6. Check the installation**

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

No row may be `FAIL`. See [Services and doctor](https://stampede.autonomousorganizations.ai/production/services-and-doctor.md) for each row.

On a macOS install built from source, rerunning `./install.sh --name NAME` with the newer tree replaces the binary and reruns `service install`. Stop the workers and back up the home first in the same way.

## Rollback

When the release did not move the schema:

```bash theme={null}
stampede service stop
install -m 755 ~/stampede-previous ~/.local/bin/stampede
stampede service install
```

When the release moved the schema, the old binary cannot read the store, so put the backup back as well:

```bash theme={null}
stampede service stop
install -m 755 ~/stampede-previous ~/.local/bin/stampede
mv ~/.stampede ~/.stampede-failed-upgrade
mv ~/.stampede-before-upgrade ~/.stampede
stampede service install
```

Everything done after the backup is lost. Before going back in either case, remove any configuration key the older release does not know (the table below names them), or the older binary refuses the file.

If you are going back from 0.5.2 or later to 0.5.1 or earlier and a webhook worker was installed, run `stampede service uninstall webhook` with the newer binary still installed and check that the unit is gone. An older binary cannot run or remove a webhook unit.

## Store schema and configuration changes

| Release | Store schema | New configuration (refused by older binaries) |
| - | - | - |
| 0.5.3 | none (stays 26) | none |
| 0.5.2 | 25 to 26 | `[webhook]` and `[[webhook.route]]` |
| 0.5.1 | 24 to 25 | `auto_load` in `[persons.NAME]` |
| 0.5.0 | 23 to 24 | `[rooms]` |
| 0.4.9 | none (stays 23) | `[tools] project_instructions`, `[persons.NAME]` |
| 0.4.8 | none (stays 23) | none |
| 0.4.7 | 22 to 23 | `[tools] turn_input_tokens` |
| 0.4.6 | none (stays 22) | none |
| 0.4.5 | none (stays 22) | none |
| 0.4.4 | 21 to 22 | none |
| 0.4.3 | none | none |
| 0.4.2 | none | none |
| 0.4.1 | to 21 | none |

The migration runs on the first start of the new binary, whichever command starts first.

## Behaviour changes per release

| Release | What to check before or after upgrading | |
| - | - | - |
| 0.5.3 | A webhook route whose person is free, operator or may run any program (maintainer) is disabled at worker start and answers 401. Check `stampede doctor` and `stampede webhook routes` first, and give each route a person made with `stampede person create NAME --policy research`. A delivery that a 0.5.2 worker queued for such a route settles `failed` and never runs. | |
| 0.5.2 | New webhook worker. Nothing starts until `[webhook]` has a route; `doctor` shows `webhook not configured`. | |
| 0.5.1 | `stampede skills install` needs a working model profile for its smoke test. Skills installed by hand keep working and read as invocation `any`. | |
| 0.5.0 | `run_command`'s default time limit is 60 seconds (was 30). A run recorded by 0.4.9 is not resumed automatically. | |
| 0.4.9 | Runs load `AGENTS.md`, `CLAUDE.md` and `STAMPEDE.md` from their directory (the gateway's `workdir`) and send the text to the model provider. To turn this off, add `project_instructions = false` under `[tools]` or in a `[persons.NAME]` table, after installing the binary and before `service install`. | |
| 0.4.8 | A command that reaches its time limit returns a timed-out result and the run continues. A person that messaged another person also sends its own final answer to its requester. | |
| 0.4.7 | Gateway requests carry the chat's earlier requests and answers; the first request after the upgrade starts with none. Replies are sent as Telegram HTML. An unquoted shell operator (\` | `, `&&`, `;\`, redirects) in a command is refused. |
| 0.4.6 | A free person on a `full_access = false` home runs any program, and can no longer save a model profile or MCP server from chat. A person's sub-agent runs its person's programs and MCP tools. | |
| 0.4.5 | New presets. `person create NAME --allow-tool X` without `--policy` is refused; add `--policy research`. A 0.4.4 binary refuses a maintainer person's record. | |
| 0.4.4 | None beyond the schema step. | |
| 0.4.3 | Runs recorded by 0.4.2 that were capped or failed show `stop: unknown (recorded before 0.4.3)`. | |
| 0.4.2 | A builder whose list is exactly the earlier preset gains `gh`, `glab`, `node`, `npm` and `npx`. A run recorded by 0.4.1 is not resumed. | |
| 0.4.1 | A 0.4.0 binary refuses the store once 0.4.1 has opened it. | |

## Runs in flight

A run recorded by an older binary may be refused automatic resume after the upgrade when the release changed what the run's access means or what tools it has. It is refused rather than resumed under different rules. Finish or conclude long runs (`stampede runs conclude RUN_ID`) before upgrading if you need them to complete.

Going back to an older binary has a similar limit: a run recorded by a newer version can carry state the older binary reads as corrupt. Finish or conclude those runs before downgrading.


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