Manage runners

Set up a Mac

Install Mirage on a personal or dedicated Mac and choose which jobs it can run.

A paired Mac supplies execution capacity to Mirage’s local-infrastructure provider. Jobs can use that capacity as their normal route or in a provider comparison. Your workflow can also use GitHub-hosted fallback when the Mac is unavailable.

Requirements

Use an Apple-silicon Mac running macOS 26. You need administrator access for the initial installation, an internet connection, and a GitHub account connected to Mirage. Both personal laptops and dedicated CI Macs use the same host service.

Leave room for downloaded runner images as well as each running job. The default Linux job uses 2 CPUs, 8 GiB memory, and a 6 GiB disk budget; Runner labels lists the defaults for every label. Mirage also reserves memory and disk for the host. The machine’s readiness checks report whether the selected configuration fits.

Install and pair

Run this command in Terminal on the Mac or over SSH. Setup asks which runners to enable and, for macOS, the maximum concurrent jobs and what resources each gets. Approve installation, then open the link shown in Terminal on any device. Sign in to Mirage if needed, check the verification code, choose the GitHub account that will manage this Mac, and confirm. Setup pairs the Mac automatically.

Terminal · interactive Mac setup

bash <(curl -fsSL https://mirageci.com/bootstrap/macos)

Choose personal for a laptop that may sleep or dedicated for a CI Mac that should stay awake while connected. Both choices install the same package.

The bootstrap command downloads and verifies the signed host package, which installs the background service, the menu-bar app, and the mirage CLI. From an active Mac desktop session, setup opens the menu-bar app and registers it to start at future logins. After an SSH-only installation, open Mirage.app once from the desktop to enable launch at login. The approval link expires after twenty minutes; rerun setup if it expires.

Once paired, open the Mac in Machines. Confirm the intended GitHub account is listed under Available to. Wait for the runner profile you need to show Ready before sending it a job.

Enable runner profiles

Profile	Additional setup
Linux arm64	Wait for the initial image download and self-test.
Linux x64	Install Rosetta on the Mac and wait for the x64 self-test.
macOS arm64	Choose macOS runners during interactive bootstrap. It prepares and tests the image under the background service.

To accept Apple’s license and install Rosetta from Terminal:

Terminal · Rosetta for Linux x64

softwareupdate --install-rosetta --agree-to-license

If you skipped macOS during setup, run the bootstrap command again and choose macOS runners. A paired Mac keeps its identity and does not need another approval.

FileVault is supported, but someone must unlock the startup disk after a cold boot. The optional menu-bar app runs when a desktop user opens it.

Resources and availability

A connected Mac can be unavailable for new jobs while it prepares an image, runs a job, is paused, or lacks safe resource headroom. Personal Macs also stop accepting new work on battery by default or under thermal pressure. Check the machine page’s profile status and suggested next step.

Set the CPU, memory, and disk Mirage may use in Settings › Resource budget on the machine page; In use above it shows what holds that budget now. The Host reserve keeps resources free for the Mac. Mirage stores the budget with your account, and the Mac applies changes after active jobs finish; the page says when a change is still waiting. Workload sizes belong to each job: open Job routes in Repos to set its allocation. Linux jobs run concurrently while their requests fit the budget. macOS CI and agent VMs share an allowance of at most two macOS guests.

Linux x64 jobs run through Rosetta and usually need more memory than the same work on arm64; give those jobs a larger memory allocation. Older agents retain their legacy concurrency and sizing settings until you update Mirage.

Terminal · pause or resume new work

mirage host configure --pause
# When you want to accept jobs again:
mirage host configure --resume

The machine page’s Settings › Keep awake prevents idle system sleep while connected. It does not override closing a laptop lid, explicit sleep, shutdown, or power loss.

To keep a Linux or macOS VM and its disk for agent work while this Mac continues serving CI, see Agent VMs on a Mac.

Updates and removal

The background host service checks for signed updates automatically and waits for active work to drain. Its CLI updates in the same verified slot, including on headless Macs. The menu-bar app checks for and installs signed updates while it is running. It starts at login after registration unless you disable that login item in macOS System Settings. You can request an immediate host check with mirage host update.

Before removing your last runner, restore your workflows’ GitHub-hosted labels. Then run mirage host uninstall on the Mac and approve the administrator prompt. Uninstalling removes the host service and its local state; running the service again requires installation and pairing.

To remove the Mac from the fleet, open its machine page in Machines and choose Delete machine…. Delete any retained Agent VM disks first. The Mac's personal controller or an organization owner may confirm deletion. It revokes pairing and sharing access; past run history is kept. Active work on a connected Mac must finish first; jobs on an unreachable Mac may be interrupted. The host software stays installed until you uninstall it.