# 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](https://mirageci.com/docs/runner-labels.md)
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
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:

```bash
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.

> **Native macOS works without a host desktop session.**
>
> The background service runs macOS guests as the restricted `_mirage` account
> with its own keychain. SSH setup works, and no host desktop login or automatic
> login is required. Wait for the macOS profile to report Ready before use.
>
> For an existing GUI-bridge installation, pause the Mac, drain CI and stop active
> agent VMs, then rerun bootstrap to install the current signed package. Retained
> agent VM disks are preserved. Resume after the profile becomes Ready.

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:

```bash
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](https://mirageci.com/docs/agent-vms.md).

## 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](https://mirageci.com/docs/connect-github.md). 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](https://mirageci.com/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.