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

# Services and doctor

> Run Stampede's workers under launchd or systemd with stampede service, read their logs, and check an installation with stampede doctor.

Schedules, Telegram, webhooks and requests from paired machines are served by long-running workers, so they must keep running after you close the terminal and come back after a reboot or a crash. `stampede service` hands the workers to the operating system's supervisor, and `stampede doctor` tells you whether the whole installation is healthy.

## Workers

| Worker | What it serves | Installed when |
| - | - | - |
| `node` | Inbound requests from paired machines, and delivery of queued outbound ones ([Multiple machines](https://stampede.autonomousorganizations.ai/teamwork/multiple-machines.md)). | Always. Needs a node identity (`stampede node init`). |
| `schedule` | Timed tasks of every person ([Schedules](https://stampede.autonomousorganizations.ai/start/schedules.md)). | Always. |
| `gateway` | The Telegram bot ([Telegram](https://stampede.autonomousorganizations.ai/start/telegram.md)). | `[gateway.telegram]` is configured. |
| `webhook` | The signed webhook listener ([Webhooks](https://stampede.autonomousorganizations.ai/start/webhooks.md)). | `[webhook]` has at least one route. |

Each worker is the same binary started as `stampede service run WORKER`. A worker loads `~/.stampede/env` and `config.toml` itself when it starts.

## Service commands

```bash theme={null}
stampede service install            # write the units and start every configured worker
stampede service install --print    # print the units without writing them
stampede service status             # one line per worker
stampede service start [WORKER]
stampede service stop [WORKER]
stampede service restart [WORKER]
stampede service reload [gateway]   # the gateway re-reads its member and group lists
stampede service uninstall [WORKER] # stop, unregister and remove the unit files
stampede service uninstall --orphans [--dry-run]
```

`start`, `stop`, `restart` and `uninstall` act on one worker when you name it, and on every installed worker when you do not. `WORKER` is `node`, `schedule`, `gateway` or `webhook`.

`install` is the command to rerun after an upgrade or after adding a gateway or webhook section. It leaves an identical unit alone, rewrites a unit it generated when the binary moved or the version changed, and refuses a unit it did not generate or that was edited since, naming the file. It prints `service: nothing to do` when nothing changed.

`start` and `restart` wait up to 35 seconds for the worker's first heartbeat before reporting success.

`reload` applies only to the gateway. It makes the running gateway re-read the member and group lists without a restart. Any other change to `config.toml` or the env file takes effect at the next `restart`.

`uninstall --orphans` removes registrations left by an installation whose home no longer exists. Deleting `~/.stampede` without `service uninstall` first leaves the supervisor retrying a binary or home that is gone; `--dry-run` lists what would be removed.

### Supervisors

| Platform | Supervisor | Unit location |
| - | - | - |
| macOS | launchd agents | `~/Library/LaunchAgents` |
| Linux | systemd user units | `~/.config/systemd/user` |

Units are named `stampede-WORKER-TAG`, where the tag is derived from the home, so two users on one host never collide. A unit runs the installed binary by absolute path, sets only `HOME`, and carries no credentials. On Linux, `install` also enables linger for the user so the units keep running with no login session; `loginctl disable-linger` reverts it.

### Status

`stampede service status` prints one line per worker and exits 0 only when every installed worker is running.

| State | Meaning | What to do |
| - | - | - |
| `running (pid N, heartbeat S s ago)` | The process is alive and its loop is turning. | Nothing. |
| `starting` | The supervisor started it and no heartbeat is written yet. Normal for a few seconds after a start. | Wait; if it persists past 30 seconds it is wedged. |
| `stopped` | The unit exists and no process runs. | `stampede service start WORKER` |
| `failed (pid N exited: REASON)` | The last attempt exited and left an error record. The supervisor may already be retrying. | Read the reason and the worker's log, fix the cause, restart. |
| `wedged` | The process is alive but its heartbeat is stale. | `stampede service restart WORKER`, then read the log. |
| `running outside the supervisor` | A live heartbeat from a hand-started `stampede service run`. | Stop the hand-started process, then `service start`. |
| `not installed` | No unit file. | `stampede service install` |
| `not configured` | An optional worker (gateway or webhook) with no configuration and no unit. | Nothing, unless you meant to configure it. |
| `records unreadable` | A file under `~/.stampede/run/` is a symlink, has a loose mode, belongs to another user or is not valid. | Fix the file named in the line. |

## Logs and heartbeats

| Path | Contents |
| - | - |
| `~/.stampede/logs/WORKER.log` | The worker's log, rotated before 4 MiB. |
| `~/.stampede/run/WORKER.heartbeat` | Written every 30 seconds while the loop runs. Stale after three missed intervals. |
| `~/.stampede/run/WORKER.error` | The reason the last attempt died before it wrote a heartbeat. |

```bash theme={null}
tail -n 50 ~/.stampede/logs/gateway.log
```

Logs carry fixed sentences, ids and kinds. They never carry keys or the bot token.

## stampede doctor

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

`doctor` checks the installation and prints one row per check: a status, a label and a detail. It is read-only: it creates, repairs and migrates nothing. It exits 1 when any row is `FAIL`, and evaluates every row first, so you see every problem in one run. Rows never contain provider responses, keys, base URLs or file contents, so the output is safe to paste into a support request.

| Status | Meaning |
| - | - |
| `ok` | The check passed. |
| `WARN` | Worth a look. Does not change the exit code. |
| `FAIL` | A problem. Makes `doctor` exit 1. A detail starting `unavailable:` means the check could not run because of another failure. |
| `skipped` | Not checked, because of `--offline`, because the check ran inside a run, or because there was not enough data. |

The last line summarises the rows: `doctor: all rows green` only when nothing failed, warned or was skipped; otherwise `doctor: N red`, with the counts of unavailable, skipped and warned rows.

`--offline` skips every row that needs the network (model transports, MCP server probes and peers) and shows them as `skipped`.

### Rows

| Label | What it checks |
| - | - |
| `config parse` | `config.toml` exists, is private and is valid TOML. Errors give a line and column, never the text. |
| `config load` | The file loads with the program's schema. Shows the profile names, `full_access`, `turn_model_calls` and `turn_input_tokens`. |
| `state directory` | Whether a configured `[tools]` root contains `~/.stampede`. Such a root grants nothing inside the home, and the row is `FAIL`. With `full_access = true` the row says no carve-out applies. |
| `gateway` | `not configured`, or the member, group and pending-sender counts, the workdir, and the persons any member can address that may run programs. |
| `webhook` | `not configured`, or the route count and bind address. `WARN` when the bind is not loopback. |
| `webhook route` | `FAIL` for each route the worker would disable; `WARN` for a served route whose person may start programs. |
| `permissions` | One row per private path: the home, `config.toml`, `runtime/`, `cards/`, `run/`, `logs/`, `memory/`, `env` and `secrets.enc`. Optional paths that do not exist get no row. |
| `transport NAME` | One per model profile: a single request for the provider's model list, which generates nothing. For a session profile, whether the CLI is on `PATH`. |
| `effort NAME` | `WARN` when `effort` is set on an Anthropic model it cannot be applied to. |
| `mcp LABEL` | One per `[[mcp]]` server: the command resolves, every `env_passthrough` variable is set, and the server starts and lists its tools within 30 seconds. |
| `context NAME` | One per profile: the fixed part of a console request (system prompt, tool schemas, output reserve, framing) against the profile's context window. |
| `cache NAME` | Prompt-cache hit rate over the last day's runs of five or more calls. `WARN` under 50 percent. |
| `skills` | `WARN` for a pinned skill (`auto_load`) that will not load, or pins that cost more than half of `turn_input_tokens`. |
| `node identity` | The node is initialised and does not advertise `0.0.0.0`. |
| `service WORKER` | One per worker, from its heartbeat, in the same states as `service status`. |
| `peers` / `peer NAME` | `none pinned`, or one signed status ping per pinned peer. |
| `schedules` / `schedule PERSON/NAME` | Every schedule with its next fire, `due` or `paused`. |
| `version` | The binary version. |

### Common fixes

| Row and detail | Fix |
| - | - |
| `config parse`: does not exist | `stampede init` |
| `config load`: an unknown key | Remove or correct the key. The file refuses unknown keys, so a key from a newer release fails on an older binary. |
| `permissions`: a loose mode | `stampede init` tightens it. A symlink, another owner or a group or world write bit must be fixed by hand. |
| `permissions`: env refused | `chmod 600 ~/.stampede/env` and make sure you own it. Every `transport` row then shows `unavailable: env not loaded`. |
| `transport`: credentials rejected (HTTP 401 or 403) | Correct the key in `~/.stampede/env`, then `stampede service restart`. |
| `transport`: no answer within 5s, or unreachable | Check the host's network, DNS and `ca-certificates`, and the profile's `base_url`. |
| `context`: prompt overhead exceeds window | Raise `context_window_tokens` on the profile, or offer fewer tools (fewer MCP servers). |
| `node identity`: not initialized | `stampede node init NAME --listen IP:PORT --advertise IP:PORT` |
| `service WORKER`: not installed | `stampede service install` |
| `service WORKER`: installed but not running | `stampede service start WORKER` |
| `service WORKER`: last start failed | Read the reason and `~/.stampede/logs/WORKER.log`, fix it, `stampede service restart WORKER`. |
| `peer NAME`: no response | The peer's node worker is down, its address changed, or another process holds the port. Run `doctor` on the peer. |
| `peer NAME`: refused | The node at that address is not the pinned identity. Export its card again and pin it again. |
| `gateway`: the variable named by `token_env` is not set | Add the token to `~/.stampede/env` under that name. |
| `gateway`: workdir does not exist, or overlaps the state directory | Create the directory, outside `~/.stampede`. |
| `gateway`: a configured value is part of a fixed line | A key or env value is so short it appears in a line the bot sends. Change the value. |
| `webhook route`: route disabled | Store the missing vault entry (at least 32 bytes for a secret), or give the route a person made with `--policy research`. |
| `state directory`: a root contains the state directory | Narrow `read_paths` or `write_paths` so no root is `~/.stampede` or above it. |

> [!NOTE]
>
> A green `gateway` row checks the configuration and paths only. It never calls the Telegram Bot API, so a wrong but well-formed token shows up as `getMe failed (unauthorized)` in `~/.stampede/logs/gateway.log`. Send a private `/start` from an allowed account before you hand the bot to anyone.

`doctor` reads the env file and environment of its own invocation. It does not prove that a running worker loaded the same values, so restart the workers after editing either.


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