RelayRunner docs: RelayRunner for Mac Page: https://relayrunner.dev/docs/get-started/mac-app Markdown: https://relayrunner.dev/docs/get-started/mac-app.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 (this page) - 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 - 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 --- # RelayRunner for Mac > A menu bar app that turns your Mac into a GitHub Actions runner with one switch. RelayRunner for Mac puts your Mac online from the menu bar, with nothing to keep open in a terminal. It does what `relayrunner connect` does, and the CLI is built in. It needs a Mac with Apple silicon and macOS 14 or newer. ## Install [Download RelayRunner for Mac](/mac/download), open the DMG and drag RelayRunner to Applications. Or install it with Homebrew: ```sh brew install --cask relayrunner/tap/relayrunner ``` If Homebrew asks you to trust the tap first, run `brew trust relayrunner/tap` and try again. ## Turn it on Click the robot head in the menu bar and turn RelayRunner on. The first time, it asks who can run jobs on this Mac and opens your browser to sign it in, the same as `connect`. While it's on, the Mac takes jobs, each in its own Linux VM. The head is faded while the Mac isn't taking jobs and shows a dot while a job runs. ### The menu The menu has a switch to turn the Mac on and off, with a line beside it that says what it's doing: waiting for jobs, how many are running and waiting, or when a pause ends. Each running job shows its name, workflow and repo, how long it has run and a bar against how long it usually takes on this Mac, with about how long it has left. Once it's clearly slower than usual, at least 30 seconds and a quarter over, the bar turns orange. Below that are **Pause New Jobs**, **Jobs…**, **Open Dashboard**, **Settings…** and **Quit RelayRunner**. ### Jobs window **Jobs…** (⌘J while the menu is open) lists the jobs running or waiting on this Mac, then every job it ran in the last week. Filter by result, repo, workflow and time, or search by name. Pick a job to see its steps on a timeline and, for a failed one, the step that failed, GitHub's annotations, the end of its log and, when the workspace has AI on, the likely cause. Drag the line between the list and the job to resize them. When every slot was busy and jobs went to another runner in the last hour, a note above the list says how many. If the Mac has room for more, **Allow N Jobs at Once** raises the number of jobs at once by one: the app pauses new jobs, waits for the running ones to finish and comes back with the extra slot. Otherwise the button opens Settings. ### Pause **Pause New Jobs** stops new jobs for an hour, four hours, until tomorrow morning or until you resume. Running jobs finish first. The menu says when the pause ends, and **Resume New Jobs** ends it early. ## Settings Settings has the same options as `connect`'s flags: how many jobs run at once, each VM's CPUs and memory, whether the Mac also takes macOS jobs, and whether jobs can reach your local network. See [Isolated jobs on a Mac](/docs/runners/self-hosted#isolated-jobs-on-a-mac) for what each one does. The **Workspaces** tab picks which workspaces the Mac takes jobs from and who can run them. ## With the CLI The app and the CLI share their sign-in, so a Mac you already connected with `npx relayrunner connect` is signed in already. Only one of them runs at a time: quit `connect` before you turn the app on. They share their job history too, which [`relayrunner history`](/docs/reference/cli#history) lists. ## Updates The app checks for updates about once a day and offers to install them. With Homebrew, `brew upgrade --cask relayrunner` works too. To check now, open Settings › About and click **Check for Updates…**. **Show Log** is there too.