Self-hosted macOS runners

Self-hosted macOS runners let Terragon run tasks on a Mac you control. Each task runs inside a full macOS VM, so browsers, desktop tooling, and macOS-specific builds stay inside the guest VM rather than on your host.

Connect A Mac

The installer opens Terragon in your browser, shows the Mac requesting approval, and asks you to approve it for your signed-in account. After approval, Terminal continues automatically.

Terragon handles the runner connection after browser approval. Setup prepares local tools, opens or reports Mac approval prompts when needed, starts a background service, connects the Mac, and waits until Terragon sees the runner check in. During the VM test, Terminal shows clone, boot, and SSH progress while the private proof report is saved locally.

Mac setup is idempotent. If a macOS prompt or local blocker stops setup, approve or fix the item shown in Terminal or Runners, then run Mac setup again from Settings -> Runners.

What Setup Checks

Before the Mac can accept tasks, Terragon verifies:

• Supported Apple Silicon Mac on macOS 13 or newer.
• macOS can run isolated virtual machines.
• Local tools and permissions needed for setup.
• At least 40 GB of free disk.
• A throwaway macOS VM can boot, run a readiness command, return output, and be cleaned up.
• The background runner service is healthy and has recently checked in with Terragon.

The Runners page contains one ordered list with Terragon Cloud and your self-hosted runners. Cloud maps to Terragon-managed cloud sandboxes. Self-hosted macOS runners map to full macOS VMs on your Mac.

Terragon provides the managed base VM for normal setup. You do not need to choose an image or prepare a local base VM. Custom local VM images are advanced and should already allow guest SSH.

Mac setup installs Terragon's managed VM tooling when it is available, and falls back to standard local installation steps when needed. Users still run the same Set up this Mac flow either way.

When a task runs on a macOS VM, Terragon still runs your normal repository setup script. Terragon adapts common Linux package-manager setup steps for the macOS guest where possible, so most projects do not need a separate setup script to start on a Mac runner.

Choose When To Use It

The Runners page shows Terragon Cloud and your connected Macs in one ordered list. Terragon Cloud maps to managed cloud sandboxes. A self-hosted Mac maps to full macOS VMs on that host.

When your runner setting is Default, Terragon Cloud remains the normal runtime until you explicitly choose a ready Mac with Use for new tasks. A self-hosted Mac must be online, recently connected, enabled, and have capacity before it can accept default tasks. If the selected Mac is not ready, locked, full, or fails before a task is assigned to it, Terragon falls back to Cloud. Other ready Macs are not silently promoted into the default route; deleting or disabling the selected Mac falls back to Cloud until you explicitly choose another ready runner.

Use Use for new tasks only when you want default tasks to prefer that Mac. Changing advanced fallback order without that button does not make a Mac the default runtime. Use Use Terragon Cloud whenever you want managed cloud sandboxes to be the normal runtime again.

Recovery

If setup needs attention, keep the Runners page open. It shows the current setup step, recent installer messages, and the exact next action.

Common recovery paths:

• Return to Terminal and approve any prompt setup opens.
• Free disk space or use a supported Apple Silicon Mac.
• Rerun the same setup after approving or fixing the reported item.