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

# Multiple machines

> Pair Stampede installations on several machines so a person on one machine can send work to a person on another.

A laptop and a server each run their own Stampede home. Once the two machines are paired, a person on one can send work to a person on the other, and the work runs on the receiving machine under the authority that machine granted. Each installation is a node: a named identity with a key pair and a UDP listener (port `7443` by default). Pairing means each node pins the other's public card.

> [!WARNING]
>
> The node listener is meant for a private network such as a Tailscale tailnet or a firewall-restricted network. Do not expose it to the public Internet.

## Pairing with install.sh

The recommended way is to install the second machine from the first with `install.sh`, which also pairs them:

```bash theme={null}
./install.sh --name laptop
./install.sh --remote ubuntu@build-01.example.com --name server --pair-with laptop --policy builder
```

| Flag | Meaning |
| - | - |
| `--name NAME` | Node name of the machine being installed: lowercase letters, digits and inner `-`, up to 63 characters. |
| `--remote USER@HOST` | Install over ssh on that machine instead of this one. |
| `--pair-with VALUE` | Pin this machine and the remote to each other. `VALUE` is this machine's own node name, or a card file path. Only with `--remote`. |
| `--policy P` | The authority ceiling each side grants the other: `research` (default), `builder` or `operator`. |
| `--port N` | UDP port for the node listener (default `7443`). |
| `--listen-ip IP` | Address to bind and advertise. Default: the single address `tailscale ip -4` prints on the machine being installed. |

Requirements for `--remote`:

* This machine is installed first (`install.sh --name`), so it has a node identity.
* ssh to the remote works without a password prompt (the script uses `BatchMode`).
* Docker runs on this machine. The script builds a Linux x86\_64 binary in Docker and copies it to the remote; nothing is compiled there.
* The remote has Tailscale with one IPv4 address, or you pass `--listen-ip`.

The script installs the binary on the remote, runs `stampede init` there, copies your `~/.stampede/env` to the remote as a `0600` file if the remote has none, creates the remote node, exchanges the two cards, pins the remote first and this machine last, and installs the remote services. A rerun with the same flags changes nothing and ends with `install: nothing to do`. After a failure, fix the cause and rerun the same command.

Check the pair from both sides:

```bash theme={null}
stampede node peer list
ssh ubuntu@build-01.example.com stampede node peer list
stampede doctor
```

## Pairing by hand

For machines installed another way. Choose a stable lowercase node name and a numeric address the other machine can reach. On each machine:

```bash theme={null}
stampede node init laptop --listen 0.0.0.0:7443 --advertise 100.64.0.2:7443
stampede node show --output ~/laptop-node.json
```

`--listen` is the local bind address; `--advertise` is the address written into the public card. Copy only the card files between the machines over a channel you trust. Never copy `node-identity.json`, which holds the private keys. Then pin the other machine's card on each side, with a ceiling:

```bash theme={null}
stampede node peer add ~/server-node.json --policy builder
stampede node peer list
```

Start the node service so inbound requests are served:

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

`stampede node peer remove NAME` rejects future requests from that peer.

## Authority

The ceiling is set locally on the receiving machine and is never taken from the peer's card. It is intersected with the addressed person's own policy, so a `builder` ceiling addressing a `research` person yields `research`.

| Ceiling | What the peer may ask a local person to do |
| - | - |
| `research` | Read-only tools. The default. |
| `builder` | File writes and the `builder` program list. |
| `operator` (also accepted as `free`) | Unrestricted, and only when the addressed local person is itself `free`. |

Use `research` unless the remote needs to change files. A request is also bounded by the receiving person's program list: a command outside it is refused on the receiving machine, and the refusal comes back as the answer.

A request from a paired machine gets at most the default turn budget (26 model calls, 500,000 input tokens), even when the receiving machine has raised its own limits. See [Budgets and timeouts](https://stampede.autonomousorganizations.ai/models/limits.md).

## Sending work

The receiving machine needs a model provider configured and the addressed person created before work arrives.

From the console, address a person on a peer with `@NODE@PERSON`:

```text theme={null}
@server@builder count the lines in input.txt in your workspace and write the number to count.txt
```

The console keeps accepting input while the remote work runs and prints its progress and final answer. Ctrl-C cancels the remote work along with the local turn. `/node status`, `/node queue` and `/node cancel` work inside the console.

From a shell, the task text comes from a file you own:

```bash theme={null}
umask 077
printf 'Inspect the service and return a readiness report. Do not deploy.\n' > ~/task.txt
stampede node send server builder --from research --task-file ~/task.txt
```

`--from` names a person on the sending machine. `node send` prints a request id before anything leaves the machine, then streams progress until the report. Follow and control requests by id:

```bash theme={null}
stampede node status server REQUEST_ID
stampede node queue
stampede node cancel server REQUEST_ID
```

If the connection drops after submission, repeat the same `node send` with `--request-id REQUEST_ID`. A completed request returns the same report and does not run twice; a changed task with the same id is rejected.

An optional `--budget-file` (an owner-only JSON file) caps the request's wall time, model and tool calls, tokens and sub-agents:

```json theme={null}
{
  "wall_time_seconds": 1800,
  "model_calls": 20,
  "tool_calls": 200,
  "input_tokens": 200000,
  "output_tokens": 50000,
  "estimated_cost_microusd": 5000000,
  "retries": 8,
  "subagents_total": 4,
  "subagents_concurrent": 2,
  "artifact_bytes": 67108864
}
```

## Undeliverable requests

A request sent while the peer's node service is stopped stays queued on the sending machine. The node worker retries the same request id until the peer accepts it or the request expires, and the console reports it undeliverable within about 30 seconds. When the peer comes back the request runs exactly once. The expiry is set in `config.toml`:

```toml theme={null}
[node]
delivery_ttl_hours = 24
```

The value is between 1 and 720 hours. It is recorded on each request when it is submitted, so a change does not extend requests already queued.

The receiving machine logs every request id to `~/.stampede/logs/node.log`. Restart its node worker with:

```bash theme={null}
stampede service restart node
```

## Node rooms

A node room is a named set of persons on paired machines, this one included, that receive the same dispatch. It is local routing configuration, separate from [task rooms](https://stampede.autonomousorganizations.ai/teamwork/mail-and-task-rooms.md).

```bash theme={null}
stampede node room create pair
stampede node room add pair server builder
stampede node room add pair laptop research
stampede node room list
```

In the console, `#pair` followed by a request sends it to every member, and each member runs it on its own machine. From a shell, `stampede node room send pair --from research --task-file FILE` does the same; `node room status`, `cancel` and `resume` take the room and the dispatch id. Each dispatch delivers the previous dispatch's reports to every member as context, so members that must not see each other's reports belong in separate rooms. A room budget is divided among the members, and wall time is the same deadline for each.


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