Three machines, three people, one cluster
harnsy started on one machine. Now several machines can work as one cluster: your server, a laptop at home, even another person’s computer with their own Claude or Codex login. Below is one example setup, and exactly what crosses between the machines, what does not, and what each side can see.
Key numbers
- 0
- ports to open when members join a home main machine through the relay
- 1
- time a join line is shown, so copy it when you issue it
- 20 s
- at most for a revoke from a terminal to close the member’s connection; from the dashboard it closes at once
- 3 days
- at most that a member keeps a borrowed harnsy Max after its token is revoked
In this article
One main machine, and members that join it
A cluster is one main machine and the machines that join it. A member can be a server of yours, a laptop at home, or someone else’s machine. Each member has its own harnsy Max key, or borrows a seat from the main machine.
Nothing about the logins moves. A member keeps its own Claude, Codex or OpenCode login on its own machine. The main machine learns each agent’s name, harness, status and folder, and it routes the messages. It gets no login and no key.
An example: Anna, Ben and Carol
Anna’s main machine is her Mac at home, behind a home router, with no public address. Ben has a laptop with his own Claude subscription and his own harnsy Max key. Carol has a computer with her own Codex subscription and no key: she borrows a seat from Anna’s.
Nobody can reach Anna’s Mac from outside, so Ben and Carol join it through the relay. On the Mac, Anna makes it the master (harnsy debug cluster init home --master), turns the relay on (harnsy debug cluster relay on) and restarts harnsy. Then she opens Nodes in her dashboard and chooses “Add to the cluster”: a name and the permissions, once for Ben and once for Carol. Each join line is shown once. Ben pastes his into “Join a master” on his laptop, and Carol does the same with hers. Nobody opens a port.
Logins stay on each machine; the main machine routes the messages.
Now Anna’s lead agent can write to ben/builder or carol/reviewer: on another machine an agent is addressed as machine/agent, and the message travels through Anna’s machine. Ben’s machine can share a folder, and Anna’s agents read it, read-only. Each machine decides what it shares.
Direct, or through the relay
If the main machine has an address the others can reach (a server, a public IP, a forwarded port), members join it directly. A member behind NAT or a firewall needs nothing special: a member always connects out and opens no port. Links between machines use TLS by default.
The relay is for a main machine that cannot be reached, like Anna’s Mac at home behind NAT. The main machine and each member that joins through it connect out to our hosted relay, which joins the two streams and copies bytes. One main machine can have direct members and relay members at once.
What each side can see
- **The relay** sees which machine connected (as a hash), when, and how much traffic. It can cut a connection; it cannot read what is inside: messages, tokens, the main machine’s key. TLS runs between your machines, and a member checks the main machine against a pin in its join line, so the relay cannot pose as the main machine.
- **The main machine** routes the messages, so it can read them. It sees each member’s agent names, harness, status and folder. It does not see logins or keys.
- **A member** sees the messages sent to its agents.
To take a machine out, revoke it on the main machine (Nodes → revoke): its connection closes at once and its seat is free again. A member that borrowed harnsy Max keeps it for up to 3 days.
Limits
A member cannot have members of its own.
Set it up
The step-by-step guide, with the commands and what you see after each step, is on the relay page. The relay needs a harnsy Max key on the main machine.
Several machines, one cluster
harnsy joins machines into one cluster: directly, or through a relay when the main machine cannot be reached.
Step-by-step guide