Last updated 2026-05-07

Running on macOS

The runner runs cleanly on macOS without modification — but a few setup choices make day-to-day use much smoother. This page captures them.

Sandbox: prefer copy-on-write

APFS supports filesystem-level copy-on-write, which makes cp -c -R nearly free. The runner detects this and will pick CoW over plain rsync. If you want to force it: 

stax run ci  # auto-detect picks CoW on macOS APFS


# or explicitly:
curl -X POST http://localhost:4800/api/runs \
  -H 'Content-Type: application/json' \
  -d '{"workflow":"ci","sandbox":{"strategy":"copy"}}'

Auto-start the runner at login

The convenient way: a LaunchAgent that boots the runner whenever you log in. Track platform/menubar/ in the repo for the Swift menu-bar app and accompanying LaunchAgent plist; until those land, you can drop a minimal plist yourself:

~/Library/LaunchAgents/com.elloloop.stax-runner.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>            <string>com.elloloop.stax-runner</string>
  <key>RunAtLoad</key>        <true/>
  <key>KeepAlive</key>        <true/>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/stax</string>
    <string>runner</string>
    <string>start</string>
    <string>--workspace</string>
    <string>/Users/<you>/projects/<repo></string>
  </array>
  <key>WorkingDirectory</key> <string>/Users/<you>/projects/<repo></string>
  <key>StandardOutPath</key>  <string>/Users/<you>/Library/Logs/stax-runner.out</string>
  <key>StandardErrorPath</key><string>/Users/<you>/Library/Logs/stax-runner.err</string>
</dict>
</plist>
launchctl load -w ~/Library/LaunchAgents/com.elloloop.stax-runner.plist
launchctl start com.elloloop.stax-runner


# Verify
curl http://localhost:4800/health

Disable / remove with launchctl unload -w ~/Library/LaunchAgents/com.elloloop.stax-runner.plist.

Menu-bar app

A native Swift menu-bar app lives under platform/menubar/ (in development at the time of writing). It will surface runner status, recent runs, and quick workflow triggers without keeping a terminal open.

Xcode workflows

Both maxim-lobanov/setup-xcode and actions/setup-xcode are shimmed: 

- uses: maxim-lobanov/setup-xcode@v1
  with:
    xcode-version: '15.4'
- run: |
    xcodebuild test \
      -scheme MyApp \
      -destination 'platform=iOS Simulator,name=iPhone 15,OS=17.5'

The shim runs xcode-select -s and looks for installed Xcode versions under /Applications/Xcode_*.app.

Common gotchas

  • Port 4800 in use. Use lsof -i :4800 to find the offender, or start the runner on a different port: stax runner start --port 4900.
  • SIP and code-signing. Mounted dmgs / network volumes can break git worktree; use strategy: 'copy' when running off external drives.
  • Spotlight indexing the sandbox dir. Add /tmp/runner-sandboxes to System Settings → Spotlight → Privacy to keep your CPU happy.