Installing the agent

The agent polls the dashboard for work, claims a job for one specific phone, runs it, and streams progress back. Every connection is outbound. Nothing listens on a public port, and nothing here dials into your machine.

While a job runs it holds a lease on that phone, renewed as it reports progress. If the Mac sleeps or the process dies, the lease lapses and the run is marked failed rather than leaving the phone stuck.

Add a machine in the dashboard and copy the command. The token identifies that Mac, so treat it like a password.

curl -fsSL https://appfarmmagic.com/install.sh | sh -s -- afm_agent_...

The installer checks the machine before touching anything, then:

• unpacks the agent into ~/.appfarmmagic/agent
• installs bun if it is missing, because the dependency install is large
• writes the token to ~/.appfarmmagic/env, readable only by you
• registers a launchd job so it restarts on login and after a crash

The most common install failure is a Mac pointed at the command line tools rather than Xcode itself. Those cannot build for a device, so the installer stops early with:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Run that, then run the install command again.

A scheduled run only fires if the agent is awake, so the Mac must not sleep. In System Settings → Displays → Advanced, turn on “Prevent automatic sleeping when the display is off”, and leave the machine plugged in.

The agent writes to ~/.appfarmmagic/logs. If a run fails without an obvious reason, that is where the detail is. Per-run output also appears in the dashboard under the execution itself.

launchctl bootout gui/$(id -u)/com.appfarmmagic.agent
rm -rf ~/.appfarmmagic ~/Library/LaunchAgents/com.appfarmmagic.agent.plist

That stops the job and deletes the agent along with the token file it kept on disk.