RelayRunner docs: macOS and iOS builds on your Mac Page: https://relayrunner.dev/docs/guides/mac-builds Markdown: https://relayrunner.dev/docs/guides/mac-builds.md All pages: https://relayrunner.dev/docs/llms.txt Other pages (Markdown): - Route GitHub Actions jobs to any runner: https://relayrunner.dev/docs/get-started/overview.md - How it works with GitHub Actions: https://relayrunner.dev/docs/get-started/github-actions.md - Quickstart: https://relayrunner.dev/docs/get-started/quickstart.md - Install the CLI: https://relayrunner.dev/docs/get-started/install.md - RelayRunner for Mac: https://relayrunner.dev/docs/get-started/mac-app.md - Set up with an agent: https://relayrunner.dev/docs/get-started/agents.md - Move your workflows over: https://relayrunner.dev/docs/get-started/move-over.md - Principles: https://relayrunner.dev/docs/concepts/principles.md - Routing: https://relayrunner.dev/docs/concepts/routing.md - Runner order: https://relayrunner.dev/docs/concepts/runner-order.md - Optimized checks: https://relayrunner.dev/docs/concepts/optimized-checks.md - Spend controls: https://relayrunner.dev/docs/guides/spend-controls.md - Providers: https://relayrunner.dev/docs/runners/providers.md - Your machines: https://relayrunner.dev/docs/runners/self-hosted.md - GitHub-hosted: https://relayrunner.dev/docs/runners/github.md - Hosted providers: https://relayrunner.dev/docs/runners/hosted.md - Runner labels: https://relayrunner.dev/docs/reference/labels.md - Add a provider: https://relayrunner.dev/docs/contribute/add-provider.md - Run CI on your laptop while you work: https://relayrunner.dev/docs/guides/laptop-ci.md - macOS and iOS builds on your Mac: https://relayrunner.dev/docs/guides/mac-builds.md (this page) - Share your team's machines: https://relayrunner.dev/docs/guides/team-machines.md - Keep up with coding agents: https://relayrunner.dev/docs/guides/agent-surge.md - Activity and history: https://relayrunner.dev/docs/dashboard/activity.md - Signals: https://relayrunner.dev/docs/dashboard/signals.md - Performance: https://relayrunner.dev/docs/dashboard/performance.md - Usage and savings: https://relayrunner.dev/docs/dashboard/usage.md - Telemetry: https://relayrunner.dev/docs/dashboard/telemetry.md - AI: https://relayrunner.dev/docs/dashboard/ai.md - CLI: https://relayrunner.dev/docs/reference/cli.md - relay.yml inputs: https://relayrunner.dev/docs/reference/relay-inputs.md - Repo config: https://relayrunner.dev/docs/reference/repo-config.md - MCP server: https://relayrunner.dev/docs/reference/mcp.md - RelayRunner API: https://relayrunner.dev/docs/reference/api.md - Workspaces and members: https://relayrunner.dev/docs/dashboard/workspaces.md - GitHub App: https://relayrunner.dev/docs/reference/github-app.md - Security: https://relayrunner.dev/docs/reference/security.md - Data and privacy: https://relayrunner.dev/docs/reference/privacy.md - Remove RelayRunner: https://relayrunner.dev/docs/dashboard/remove.md - Troubleshooting: https://relayrunner.dev/docs/reference/troubleshooting.md - Errors: https://relayrunner.dev/docs/reference/errors.md - FAQ: https://relayrunner.dev/docs/reference/faq.md - Feedback: https://relayrunner.dev/docs/contribute/feedback.md - Changelog: https://relayrunner.dev/docs/changelog.md - Agents can change your routing: https://relayrunner.dev/docs/changelog/agent-changes.md - Pick runner sizes on the dashboard: https://relayrunner.dev/docs/changelog/auto-runner-sizes.md - CLI changelog: https://relayrunner.dev/docs/changelog/cli.md - Send job logs to your tools or your own bucket: https://relayrunner.dev/docs/changelog/job-log-export.md - Mac app changelog: https://relayrunner.dev/docs/changelog/mac.md - RelayRunner for Mac: https://relayrunner.dev/docs/changelog/mac-app.md - CI traces in your observability tool: https://relayrunner.dev/docs/changelog/opentelemetry-traces.md - Platform changelog: https://relayrunner.dev/docs/changelog/platform.md - Retries, queueing and provider usage: https://relayrunner.dev/docs/changelog/retries-queueing-and-provider-usage.md - Route a repo from the dashboard: https://relayrunner.dev/docs/changelog/route-a-repo.md - Clearer run times and job sizes for members: https://relayrunner.dev/docs/changelog/run-times.md - Usual times, job history and the Mac queue: https://relayrunner.dev/docs/changelog/usual-times-and-mac-queue.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.