Workers on other machines

A coordinator on one machine starts a worker on another machine of the same account, or adopts an agent already running there. For work that needs that machine, like its simulator.

A worker can run on another machine of your account (say, a Mac kept for CI), started there or adopted from what already runs there. Use it for work that needs that machine: its simulator, its GPU, its checkout. The worker is an ordinary worker on that machine, with its own window, conversation, questions and notifications; the coordinator's st gives it work, waits for it and reads it from there.

Requirements

• st 0.3.85 or later on both machines.
• Both machines signed in to the same account.
• The coordinator's machine signed in with st login.
• The machine that takes the work allows it with st orch accept-remote on. It is off until you turn it on.
• st running on the machine that takes the work, with the hooks (st hooks install) there too.
• A Windows machine (psmux 3.4.0, st 0.3.97 or later) takes workers by adopting only: st worker start --machine to it is refused. st tries psmux when it starts; when psmux cannot keep what st needs (an older psmux, say), workers are off there and st orch accept-remote on and --machine say why.

Steps

1. Allow it on the machine that takes the work. Another machine starting agents and typing into them here is off until you turn it on, and only machines of the same account are let in.

st orch accept-remote on        # take workers from the account's other machines
st orch accept-remote status    # whether it does
st orch accept-remote off       # stop

2. Hand it over from the coordinator. Name the machine by its name, its hostname or its slug; case does not matter. st machines lists them. Naming this machine is refused: leave out --machine.

st worker start --machine ci-mac --agent claude --task sim.md
st worker wait ci-mac/%7
st worker read ci-mac/%7

As usual you ask the coordinator ("run the iOS tests on ci-mac") and it runs these.

The worker there

• The worker opens in a new window of that machine's st-remote session, made when missing, and works in its home folder there, or in --cwd.
• --owns and --worktree work as they do on one machine; the worktree is made in that machine's checkout.
• st worker start returns once the worker has started its turn there. It checks for up to 150 seconds; the trust-screen and hook checks are the same as on one machine, made on that machine.
• Its id is the machine and its pane: ci-mac/%7. st writes the machine's slug there, and the name or hostname works as well. The worker's name works in place of the pane: ci-mac/<name> (st 0.3.90 or later).
• wait, read, send, stop, list, adopt, rename and release take that id. st worker wait with no ids waits for this pane's workers on other machines too, and st worker list lists them with the machine. st worker list --all lists the workers on other machines of every run here (st 0.3.88 or later).
• The depth limits count across machines: two levels in a run, and four in the whole chain from the top coordinator down (st 0.3.88 or later on both machines).
• The worker reports with st worker done as usual, on its own machine, and the coordinator's st reads it from there.
• While the machine cannot be reached, wait counts the worker as still working, and list shows it as unreachable.

Connection

• No port to open and no SSH: the coordinator's st reaches that machine through your account.
• It goes over https only.
• It keeps the machine's access for 11 hours, in ~/.sophonz/remote/<slug>.json, so each command does not open the machine again. When the machine's address changes, it opens it again.

Adopting across machines

An agent already running on the other machine can become the coordinator's worker, its conversation kept:

st worker adopt ci-mac/%7
st worker send ci-mac/%7 "Run the UI tests on the iPhone 16 simulator."

• The other machine has to accept workers (st orch accept-remote on) for this too.
• --owns is for workers on this machine; it is refused with a remote id.
• An agent that already works for someone else is refused until it is released.
• An agent there that directs workers of its own comes in as a team: it keeps its run on its machine, its team stays there under it, and here it is one worker with (team N) in st worker list. This needs st 0.3.88 or later on both machines; an older st there puts the lead into this coordinator's run instead. See A team as a worker.

Renaming a worker there

st worker rename ci-mac/%7 ios-ci changes the worker's name on that machine and in this machine's run. This needs st 0.3.96 or later on both machines.

• That machine takes a rename only from the machine the worker works for; from any other machine it is refused.
• An older st there is refused with "st upgrade there": run st upgrade on that machine.
• The name is a label, not the machine; see A worker's name.

In the apps

A worker on another machine is listed in its coordinator's window card with that machine's icon and name; from desktop app 0.1.33 it sits under the agent it works for, even when that agent is itself a worker. On the worker's machine its window stays where it is, marked like "worker of coordinator · home-macbook".

• Desktop app. Adopt across machines by dragging window rows in the sidebar (desktop app 0.1.31 or later). What it shows and what does not work yet are in Workers on other machines in the desktop app's guide.
• Phone. The Agents chart joins workers and coordinators on other machines into the same tree. When you adopt from the phone, a machine that does not take workers is dimmed with "CI Mac doesn't take workers from other machines. On it, run st orch accept-remote on." The machine's st and agent hooks sheet says Workers from other machines: on (or off).
• Web terminal. The Agents card and the agent graph show the agents on the account's other machines too; click one to open its window on that machine. A machine that is offline is dimmed (st 0.3.92 or later).

Releasing

• From the coordinator's side (st worker release ci-mac/%7): the worker is told it works for no one, the coordinator is told not to send it work, and the run drops it.
• On the worker's own machine (Release in that machine's graph): only the worker is told. The coordinator's run still lists it.

A coordinator on a new pane

The worker on the other machine knows its coordinator by this machine's pane id, such as main-pc/%0. When this machine's tmux server goes down and st restores the sessions, the coordinator comes back as another pane, say %8. From st 0.3.88:

• The coordinator's st sees the move within about ten seconds and tells each of its workers on other machines its new pane. The worker's agent is not told anything. While the other machine cannot be reached, st tries again every minute.
• With an older st on the other machine, the coordinator's st releases the worker and adopts it again instead.
• Until it is told, the worker's st worker list on its own machine says (parent gone; its coordinator is main-pc/%8 now). With an older st on the coordinator's machine, nothing is shown.
• The coordinator's st worker list --all lists the workers on other machines of every run here and marks the ones whose coordinator is gone.
• In the sidebar a worker whose coordinator is gone shows ⚠ and Release (desktop app 0.1.33 or later, the web terminal from st 0.3.88).

See After a tmux restart for the same on one machine.

Refusals

st says why, and what to do:

Security

• Only machines of the same account, and only when the receiving machine has turned on accept-remote.
• The agents there run with that machine's own settings, permission mode included. The coordinator does not choose them.
• The control plane only opens the connection. The tasks and the answers go between the two machines' st.

Not yet

• Moving code between the machines: st worker diff, merge and pick are for workers on this machine.
• Tasks in order on another machine (st task --machine).
• Links to what a worker leaves on its machine (screenshots, logs).
• One graph of every machine of the account.

Until then, have the worker fetch from and push to the shared git remote, and say so in its task.

Also:

• Whether a machine reached only through the relay can take workers has not been confirmed yet.
• --split is for workers on this machine. --fan with --machine starts every worker of the fan on that machine.
• A team's lead adopted from another machine knows the chain above it only as far as the coordinator's machine, so the workers it starts there are not checked against levels further up.