Test on another machine's simulator

The coordinator on your main machine starts a worker on a Mac of the same account, which runs the iOS simulator tests there and reports back.

Goal. You work on one machine; the iOS simulator lives on another Mac (here called ci-mac). The coordinator hands the simulator run to a worker on that Mac, waits for it and reads what it found, without you going over there.

You need

  • Both machines signed in to the same account (st login) and sharing, with st 0.3.85 or later on both. The coordinator's machine has to be signed in.
  • On the CI Mac: st hooks install done, Claude Code signed in, and a checkout of the repository.
  • A remote both machines can fetch from and push to. st does not move code between machines yet, so the branch travels through git.
  • Whether a CI Mac reached only through a relay can take workers has not been confirmed yet.

1. Let the CI Mac take workers

On the CI Mac. It is off until you turn it on, and only machines of the same account are let in.

st orch accept-remote on
st orch accept-remote status   # check

2. Push the branch

On your main machine, so the worker can fetch it:

git push origin fix-login

3. Write the task

# Run the login UI tests on the simulator
 
In /Users/ci/src/app: git fetch origin && git checkout fix-login.
Run: xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=iPhone 16'
Do not change code. Write the failures, with their messages, to sim-report.md
and run: st doc sim-report.md --title "Simulator run"

The worker works in its home folder unless you give --cwd. Paths in the task and in --cwd are the CI Mac's.

4. Ask the coordinator

/sophonz:orchestrate Have a Claude worker on ci-mac run sim.md, wait for it,
then tell me which tests failed and why.

It runs:

st worker start --machine ci-mac --agent claude --task sim.md --cwd /Users/ci/src/app
st worker wait ci-mac/%7 --timeout 30m
st worker read ci-mac/%7

Name the machine by its name, hostname or slug. st worker start returns once the worker has started its turn on the CI Mac, and prints its id, <machine>/%N. Write the CI Mac's path in full: ~ would be turned into your own home folder by your shell before st sees it.

If the CI Mac has not said st orch accept-remote on, or its st is too old, st says so and starts nothing.

5. Watch it

  • On the CI Mac the worker opens in a new window of the st-remote session (made when missing). It runs with that Mac's own settings, permission mode included.
  • In the desktop app the worker stays under the CI Mac in the sidebar, with a machine icon and a ↳ parent · machine mark, and the coordinator's card lists it too. Click its row to watch it.
  • On the phone open the CI Mac and its st-remote session, like any other machine.
  • The web terminal's Agents card and agent graph show the remote worker too (st 0.3.92 or later).

While the CI Mac cannot be reached, st worker wait counts the worker as still working.

6. Read the results

st worker read ci-mac/%7 gives the worker's last answer and its done summary; the coordinator reports from them. The report itself was handed over with st doc on the CI Mac, so it is under that machine's Documents in the app (see Documents). st has no link to it from the coordinator's side yet.

7. Finish

st worker stop ci-mac/%7 --yes   # close the worker's window on the CI Mac

If the task let the worker push a fix, fetch it on your machine (git fetch origin). To stop taking workers, run st orch accept-remote off on the CI Mac.

More: Workers on other machines.