7443 by default). Pairing means each node pins the other’s public card.
Pairing with install.sh
The recommended way is to install the second machine from the first withinstall.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.
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:
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 abuilder 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:
/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:
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 inconfig.toml:
~/.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.#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.