Skip to main content
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.
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:
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:

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:
--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:
Start the node service so inbound requests are served:
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. 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.

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

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

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