Adding a machine

Several machines can run ctrlrelay on the same GitHub account and the same repositories. Each one takes issues the others have not claimed, each scheduled sweep runs once across them, and any machine’s status page shows all of them. This page sets up a second machine, node-b, next to a running node-a.

Read Operations: several machines on one account for how the claims work.

1. Install

Install ctrlrelay the same way as on the first machine (Getting started), the same version on every machine. A machine on a version from before the multi-machine work reads every failure comment as freeing every claim and posts claims with no machine name.

2. Its own GitHub login

Log gh in on this machine with its own token:

gh auth login

Use the same GitHub account as the other machines (claims only count when they come from the account the relay runs as), but a token of its own. A token copied between machines is revoked for all of them at once.

3. Its own agent login

Log the agent CLI in on this machine — whichever your repos use (claude, opencode or both, per agent.type and repos[].agent_type). For Claude Code, each machine can use its own subscription; it pauses on its own when its usage nears the limit (usage.pause_at). Two machines on one subscription share one set of usage numbers and pause together, which is correct. OpenCode has no usage reading of its own.

4. A config with its own node_id

Copy orchestrator.yaml from the first machine and change:

node_id: "node-b"          # a name no other machine on this account uses

The node_id is on every claim, every chat message and the status page, so two machines with the same one look like one. If you leave it out, the hostname is used, which is fine when hostnames differ. ctrlrelay refuses to start with a placeholder such as my-laptop, localhost or unknown.

Keep repos, schedules and timezone the same on every machine: the scheduled sweep is split by its scheduled time, so machines must agree on the schedule.

5. Peers, for the status page

To see every machine on any machine’s page, list the others’ status pages:

# on node-b
web:
  host: "192.168.1.21"           # an address node-a can reach
  allowed_hosts: ["node-b"]      # the name node-a uses for this machine
fleet:
  peers: ["http://node-a:8787"]
  account_label: "max-2"         # optional: which subscription, never an email

and the mirror image on node-a. A peer refuses a name it does not know (HTTP 421, shown as “bad host header”): each machine’s web.allowed_hosts must hold the name the others use for it.

6. Chat

  • Mattermost: machines can share one bot and channel. Set transport.mattermost.shared: true on every machine. Answer a question by replying to it; a message that is not a reply must start with the machine’s name, node-b: ....
  • Telegram: each machine needs its own bot (create one with @BotFather). Telegram lets one process read a bot at a time.

See Operations: chat with several machines.

7. Check it

ctrlrelay node check
✓ node_id: node-b (named on claims, chat and the page)
✓ GitHub login: <the account>
✓ agent login: works; 12% of the 5-hour window
✓ peer http://node-a:8787: reachable, node-a

--no-agent skips the agent check, which makes one tiny claude call on the subscription. The row is skipped when no repo routes to claude, and it never checks opencode: run that CLI once by hand. A peer that answers with this machine’s own name means two machines share a node_id (or the URL points back here).

8. Start it

Start the bridge, the poller and the status page as on the first machine (Operations). At startup, and while it runs, the poller warns, in its log and in chat, if another process uses its name: at startup, a peer whose status page answers with its name; while it runs, a claim under its name that another process is refreshing, on an issue it looks at. Neither is certain to catch every case, so give each machine its own node_id rather than relying on the warning.

Then open either machine’s status page: the Machines strip shows both.