RelayRunner docs: macOS and iOS builds on your Mac
Page: https://relayrunner.app/docs/guides/mac-builds
Markdown: https://relayrunner.app/docs/guides/mac-builds.md
All pages: https://relayrunner.app/docs/llms.txt

Other pages (Markdown):
- Changelog: https://relayrunner.app/docs/changelog.md
- CLI changelog: https://relayrunner.app/docs/changelog/cli.md
- CI traces in your observability tool: https://relayrunner.app/docs/changelog/opentelemetry-traces.md
- Platform changelog: https://relayrunner.app/docs/changelog/platform.md
- Retries, queueing and provider usage: https://relayrunner.app/docs/changelog/retries-queueing-and-provider-usage.md
- Optimized checks: https://relayrunner.app/docs/concepts/optimized-checks.md
- Principles: https://relayrunner.app/docs/concepts/principles.md
- Routing: https://relayrunner.app/docs/concepts/routing.md
- Runner order: https://relayrunner.app/docs/concepts/runner-order.md
- Add a provider: https://relayrunner.app/docs/contribute/add-provider.md
- Feedback: https://relayrunner.app/docs/contribute/feedback.md
- Activity and history: https://relayrunner.app/docs/dashboard/activity.md
- Performance: https://relayrunner.app/docs/dashboard/performance.md
- Remove RelayRunner: https://relayrunner.app/docs/dashboard/remove.md
- Signals: https://relayrunner.app/docs/dashboard/signals.md
- Telemetry: https://relayrunner.app/docs/dashboard/telemetry.md
- Usage and savings: https://relayrunner.app/docs/dashboard/usage.md
- Workspaces and members: https://relayrunner.app/docs/dashboard/workspaces.md
- Set up with an agent: https://relayrunner.app/docs/get-started/agents.md
- How it works with GitHub Actions: https://relayrunner.app/docs/get-started/github-actions.md
- Install the CLI: https://relayrunner.app/docs/get-started/install.md
- Move your workflows over: https://relayrunner.app/docs/get-started/move-over.md
- Route GitHub Actions jobs to any runner: https://relayrunner.app/docs/get-started/overview.md
- Quickstart: https://relayrunner.app/docs/get-started/quickstart.md
- Keep up with coding agents: https://relayrunner.app/docs/guides/agent-surge.md
- Run CI on your laptop while you work: https://relayrunner.app/docs/guides/laptop-ci.md
- macOS and iOS builds on your Mac: https://relayrunner.app/docs/guides/mac-builds.md (this page)
- Spend controls: https://relayrunner.app/docs/guides/spend-controls.md
- Share your team's machines: https://relayrunner.app/docs/guides/team-machines.md
- RelayRunner API: https://relayrunner.app/docs/reference/api.md
- CLI: https://relayrunner.app/docs/reference/cli.md
- Errors: https://relayrunner.app/docs/reference/errors.md
- FAQ: https://relayrunner.app/docs/reference/faq.md
- GitHub App: https://relayrunner.app/docs/reference/github-app.md
- Runner labels: https://relayrunner.app/docs/reference/labels.md
- MCP server: https://relayrunner.app/docs/reference/mcp.md
- Data and privacy: https://relayrunner.app/docs/reference/privacy.md
- relay.yml inputs: https://relayrunner.app/docs/reference/relay-inputs.md
- Repo config: https://relayrunner.app/docs/reference/repo-config.md
- Security: https://relayrunner.app/docs/reference/security.md
- Troubleshooting: https://relayrunner.app/docs/reference/troubleshooting.md
- GitHub-hosted: https://relayrunner.app/docs/runners/github.md
- Hosted providers: https://relayrunner.app/docs/runners/hosted.md
- Providers: https://relayrunner.app/docs/runners/providers.md
- Your machines: https://relayrunner.app/docs/runners/self-hosted.md

---

# macOS and iOS builds on your Mac

> Run macOS jobs on a Mac you own, and fall back to hosted Macs when it's busy or asleep.

macOS minutes on GitHub cost about ten times Linux minutes, so iOS and Mac builds are often most of a CI bill. A Mac mini or the MacBook you already use can run the same jobs for free.

## 1. Connect the Mac

On the Mac:

```sh
npx relayrunner connect --macos
```

`--macos` matters on a Mac with Apple silicon, which otherwise runs its jobs in Linux VMs. With it, macOS jobs run on the Mac itself, where Xcode is, and Linux jobs still run in VMs.

Leave it running. A Mac mini that stays on makes a good dedicated runner; set it to not sleep in System Settings.

## 2. Route the macOS jobs

```sh
npx relayrunner init
```

`init` gives each `macos-*` job a relay like this:

```yaml
relay-build:
  uses: relayrunner/actions/.github/workflows/relay.yml@v1
  with:
    machine: macOS
    github: macos-latest
```

`machine: macOS` means only Macs take it, never a Linux machine. Use `macOS, ARM64` to require Apple silicon.

## 3. Set the order

Keep **Self-hosted** above **GitHub-hosted** on the Router page. The Mac takes the job when it's free, and a hosted Mac takes it otherwise.

## Things to check

- **Xcode.** The job uses whatever Xcode is installed on the Mac. Select a version in the job, such as with `xcode-select`, rather than relying on the default.
- **Signing.** Keychains and certificates on the Mac are visible to the job. Route signing and release jobs only to a Mac you trust, or keep them on GitHub.
- **Simulators** and caches persist on the Mac between jobs, which makes later runs faster. Clean them up now and then.
- **Several Macs.** Connect each one. Each job goes to an idle one.

## A Mac you don't own

A leased or cloud Mac works the same way: run `relayrunner connect` on it.