Set up a Mac

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. Mirage also reserves memory and disk for the host. The machine’s readiness checks report whether the selected configuration fits.

Install and pair

Select the GitHub account you want the Mac to serve. Open Machines and select Pair Mac. Run one of these commands in Terminal on that Mac, then enter the one-time code and approve installation.

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

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

The installer downloads and verifies the signed host package. The service runs in the background; the menu-bar app is optional. You can also download the Mac installer and pair from Pair this Mac in the app.

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

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

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

With the CLI available, enable native macOS jobs and check readiness:

mirage host configure --macos-enabled true
mirage host doctor

After a restart, a desktop user must log in again for native macOS capacity. FileVault is supported, but someone must unlock the startup disk after a cold boot. Linux jobs do not require the native macOS GUI bridge.

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.

Start with one concurrent job. To change resources, use the menu-bar app or the CLI. For example, this gives each Linux runner 4 CPUs, 8 GiB memory, and a 16 GiB disk budget:

mirage host configure --linux-cpus 4 --linux-memory-mib 8192 --linux-disk-gib 16

Mirage waits for active jobs to finish before applying a runner resource change. Raising --maximum-vms also needs enough memory, CPU, and disk for all concurrent jobs. Slots are shared across the Mac’s profiles and GitHub accounts.

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

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

Updates and removal

Mirage’s host service supports signed updates and waits for active work to drain. To check for and install an update, run mirage host update. The menu-bar app and background host service have separate update checks.

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.