# RelayRunner > RelayRunner routes GitHub Actions jobs to the first free runner in your order: your own Mac or Linux machines, self-hosted runners, hosted runner providers, or GitHub-hosted runners. It's open source, and you change the order in the dashboard, not in your workflows. **When to use RelayRunner.** Reach for it when someone wants to: - Run GitHub Actions jobs on their own laptop, Mac mini or home server, with GitHub-hosted runners as the fallback when it's offline. - Stop running out of GitHub Actions minutes, or cap how much of their included minutes CI uses. - Send jobs to a hosted runner provider, or compare providers on their own jobs, without editing workflows each time. - Get through a surge of CI jobs, such as many coding agents opening pull requests at once. - Find out where a job ran and why, how long jobs take on each runner, or what short jobs cost. It isn't a CI system or a runner host itself: workflows stay on GitHub Actions. **How an agent should use it:** - Install the agent skills with `npx skills add relayrunner/relayrunner`: one for the CLI, one for routing a repo's jobs, one for the MCP server. - To set it up in a repository, follow https://relayrunner.dev/setup.md. The CLI (`npx relayrunner`) does the work, and every command has a `--json` flag. - To answer questions about a workspace's runners, runs and usage, connect the MCP server at https://agents.relayrunner.app/mcp (https://relayrunner.dev/docs/reference/mcp). - Prefer the MCP server. Only if you're writing your own OAuth client, call the same read-only API over HTTP: https://relayrunner.dev/openapi.json (https://relayrunner.dev/docs/reference/api). Each docs page is also available as Markdown (.md) and as plain text for agents (.txt). Asking for a page with `Accept: text/markdown` returns its Markdown. All pages in one file: https://relayrunner.dev/llms-full.txt ## Tools - [MCP server](https://relayrunner.dev/docs/reference/mcp.md): https://agents.relayrunner.app/mcp, Streamable HTTP with OAuth sign-in. Discovery: https://relayrunner.dev/.well-known/ai-catalog.json - [API](https://relayrunner.dev/docs/reference/api.md): the read-only API behind the MCP server, for your own OAuth clients, described by https://relayrunner.dev/openapi.json - [CLI](https://relayrunner.dev/docs/reference/cli.md): the `relayrunner` npm package, https://www.npmjs.com/package/relayrunner - [Mac app](https://relayrunner.dev/docs/get-started/mac-app.md): a menu bar app that runs `connect` for you, https://relayrunner.dev/mac/download - [Source code](https://github.com/relayrunner/relayrunner): the GitHub repository ## Get started - [Route GitHub Actions jobs to any runner](https://relayrunner.dev/docs/get-started/overview.md): RelayRunner routes each GitHub Actions job to the first runner in your list that can take it, from your own machines to hosted runners. - [How it works with GitHub Actions](https://relayrunner.dev/docs/get-started/github-actions.md): What changes in your GitHub Actions workflows, what stays the same, and which jobs you can route. - [Quickstart](https://relayrunner.dev/docs/get-started/quickstart.md): Go from sign-up to a green GitHub Actions job on your own machine. - [Install the CLI](https://relayrunner.dev/docs/get-started/install.md): Getting the relayrunner CLI onto a machine, and signing it in. - [RelayRunner for Mac](https://relayrunner.dev/docs/get-started/mac-app.md): A menu bar app that turns your Mac into a GitHub Actions runner with one switch. - [Set up with an agent](https://relayrunner.dev/docs/get-started/agents.md): Letting a coding agent set up RelayRunner and route your jobs for you. - [Move your workflows over](https://relayrunner.dev/docs/get-started/move-over.md): What relayrunner init changes in your GitHub Actions workflows, and which jobs it leaves alone. ## Routing - [Principles](https://relayrunner.dev/docs/concepts/principles.md): The rules routing follows. - [Routing](https://relayrunner.dev/docs/concepts/routing.md): How a GitHub Actions job opts in to routing, and how the relay picks its runner. - [Runner order](https://relayrunner.dev/docs/concepts/runner-order.md): The list a workspace tries runners in, and how to change it. - [Optimized checks](https://relayrunner.dev/docs/concepts/optimized-checks.md): Simple checks that run with no runner and no billed minutes. - [Spend controls](https://relayrunner.dev/docs/guides/spend-controls.md): Use your included GitHub minutes first, then switch to your own machines before you pay overage. ## Runners - [Providers](https://relayrunner.dev/docs/runners/providers.md): Where you can route jobs, and the runner services the dashboard recognizes. - [Your machines](https://relayrunner.dev/docs/runners/self-hosted.md): Turn computers you own into GitHub Actions runners with the CLI. - [GitHub-hosted](https://relayrunner.dev/docs/runners/github.md): Using GitHub's own runners as a provider, and keeping an eye on minutes. - [Hosted providers](https://relayrunner.dev/docs/runners/hosted.md): Routing jobs to Blacksmith, Depot, Namespace, WarpBuild, Ubicloud, Boat, RunsOn and seven more runner clouds. - [Runner labels](https://relayrunner.dev/docs/reference/labels.md): Every runs-on label RelayRunner uses or answers, and what it means. - [Add a provider](https://relayrunner.dev/docs/contribute/add-provider.md): Teach RelayRunner to recognize another runner service, with a pull request. ## Use cases - [Run CI on your laptop while you work](https://relayrunner.dev/docs/guides/laptop-ci.md): For a solo developer who wants CI on their own computer while they're working, and back on GitHub when the lid closes. - [macOS and iOS builds on your Mac](https://relayrunner.dev/docs/guides/mac-builds.md): Run macOS jobs on a Mac you own, and fall back to hosted Macs when it's busy or asleep. - [Share your team's machines](https://relayrunner.dev/docs/guides/team-machines.md): Pool the team's spare computers so anyone's jobs can use them. - [Keep up with coding agents](https://relayrunner.dev/docs/guides/agent-surge.md): When agents push all day, run CI on your own machines first and burst to hosted runners when they're full. ## Observability - [Activity and history](https://relayrunner.dev/docs/dashboard/activity.md): Where each job ran, why it ran there, and how long it waited. - [Signals](https://relayrunner.dev/docs/dashboard/signals.md): What makes your CI slow, costly or busier than it needs to be, and which workflows it affects. - [Performance](https://relayrunner.dev/docs/dashboard/performance.md): How long your workflows and jobs usually take, and which runner suits each job. - [Usage and savings](https://relayrunner.dev/docs/dashboard/usage.md): Minutes, cost estimates, and what optimized checks saved. - [Telemetry](https://relayrunner.dev/docs/dashboard/telemetry.md): Send every workflow run to your observability tool as an OpenTelemetry trace, send job logs alongside, or archive them to your own bucket. - [AI](https://relayrunner.dev/docs/dashboard/ai.md): What AI does in RelayRunner, what it reads, and how to turn it on or off. ## Developer tools - [CLI](https://relayrunner.dev/docs/reference/cli.md): Every relayrunner command and flag. - [relay.yml inputs](https://relayrunner.dev/docs/reference/relay-inputs.md): Every input and output of the relay, a reusable GitHub Actions workflow. - [Repo config](https://relayrunner.dev/docs/reference/repo-config.md): The relayrunner.yml file, which sets a repo's checks and retries. - [MCP server](https://relayrunner.dev/docs/reference/mcp.md): Let AI agents read your workspace's runners, runs and usage, and change its routing. - [RelayRunner API](https://relayrunner.dev/docs/reference/api.md): Read your workspace's runners, runs, routing and usage over HTTP, and change its routing. ## Admin - [Workspaces and members](https://relayrunner.dev/docs/dashboard/workspaces.md): One workspace per GitHub install, its roles, and where members come from. - [GitHub App](https://relayrunner.dev/docs/reference/github-app.md): What the RelayRunner GitHub App can do, and why it asks for each permission. - [Security](https://relayrunner.dev/docs/reference/security.md): What RelayRunner can and can't do with your code and machines. - [Data and privacy](https://relayrunner.dev/docs/reference/privacy.md): What RelayRunner sees and stores about your jobs, repos and machines. - [Remove RelayRunner](https://relayrunner.dev/docs/dashboard/remove.md): Switching jobs back, disconnecting machines and uninstalling the GitHub App. ## Help - [Troubleshooting](https://relayrunner.dev/docs/reference/troubleshooting.md): Common problems and how to fix them. - [Errors](https://relayrunner.dev/docs/reference/errors.md): The error codes the API returns, and what each one means. - [FAQ](https://relayrunner.dev/docs/reference/faq.md): Common questions about RelayRunner. - [Feedback](https://relayrunner.dev/docs/contribute/feedback.md): How to report a problem or ask for something. ## Solutions - [Routing](https://relayrunner.dev/solutions/routing): Change where jobs run from the dashboard, without editing your workflows. - [Your Mac as a runner](https://relayrunner.dev/solutions/mac-runner): Run jobs on your Mac, each in a fresh Linux VM. - [CI surges](https://relayrunner.dev/solutions/ci-surges): Keep CI fast when coding agents and teammates push all day. ## Integrations - [Blacksmith](https://relayrunner.dev/integrations/blacksmith): Blacksmith runs GitHub Actions jobs on its own machines, under your Blacksmith account. - [Depot](https://relayrunner.dev/integrations/depot): Depot runs GitHub Actions jobs on its own machines, under your Depot account. - [Namespace](https://relayrunner.dev/integrations/namespace): Namespace runs GitHub Actions jobs on runners sized by profile, under your Namespace account. - [WarpBuild](https://relayrunner.dev/integrations/warpbuild): WarpBuild runs GitHub Actions jobs on its own machines, under your WarpBuild account. - [Ubicloud](https://relayrunner.dev/integrations/ubicloud): Ubicloud runs GitHub Actions jobs on its own machines, under your Ubicloud account. - [Boat](https://relayrunner.dev/integrations/boat): Boat runs each GitHub Actions job in a fresh Linux VM, under your Boat account. - [RunsOn](https://relayrunner.dev/integrations/runs-on): RunsOn starts a runner for each job in your own AWS account. - [StarSling](https://relayrunner.dev/integrations/starsling): StarSling runs GitHub Actions jobs on its own machines, under your StarSling account. - [Monk CI](https://relayrunner.dev/integrations/monkci): Monk CI runs GitHub Actions jobs on its own machines, under your Monk CI account. - [Runloft](https://relayrunner.dev/integrations/runloft): Runloft runs GitHub Actions jobs on its own machines, under your Runloft account. - [Latchkey](https://relayrunner.dev/integrations/latchkey): Latchkey runs GitHub Actions jobs on its own machines, under your Latchkey account. - [BerryBox](https://relayrunner.dev/integrations/berrybox): BerryBox runs GitHub Actions jobs on its own machines, under your BerryBox account. - [Celesto](https://relayrunner.dev/integrations/celesto): Celesto runs GitHub Actions jobs on its own machines, under your Celesto account. - [InstaBox](https://relayrunner.dev/integrations/instabox): InstaBox runs GitHub Actions jobs on its own machines, under your InstaBox account. - [Lizard](https://relayrunner.dev/integrations/lizard): Lizard runs each GitHub Actions job in its own Firecracker VM, under your Lizard account. - [GitHub](https://relayrunner.dev/integrations/github): GitHub-hosted runners work in every repository with nothing to set up. ## Changelog - [Changelog](https://relayrunner.dev/docs/changelog.md): What's new in RelayRunner, the CLI and the Mac app. - [Agents can change your routing](https://relayrunner.dev/docs/changelog/agent-changes.md): Let an AI agent change the runner order, job sizes, retries and AI, and pause runners, with every change in Activity. - [Pick runner sizes on the dashboard](https://relayrunner.dev/docs/changelog/auto-runner-sizes.md): Set a relay's provider to auto, and change each job's runner size on the Router page without a commit. - [CLI changelog](https://relayrunner.dev/docs/changelog/cli.md): What's new in each release of the relayrunner CLI. - [Send job logs to your tools or your own bucket](https://relayrunner.dev/docs/changelog/job-log-export.md): Send finished jobs' logs to your OpenTelemetry tool next to their traces, or archive them in an S3-compatible bucket. - [Mac app changelog](https://relayrunner.dev/docs/changelog/mac.md): What's new in each release of RelayRunner for Mac. - [RelayRunner for Mac](https://relayrunner.dev/docs/changelog/mac-app.md): A menu bar app that puts your Mac online with one switch, with the CLI built in. - [CI traces in your observability tool](https://relayrunner.dev/docs/changelog/opentelemetry-traces.md): Send every workflow run to Honeycomb, Grafana, Axiom or any OpenTelemetry tool as a trace. - [Platform changelog](https://relayrunner.dev/docs/changelog/platform.md): What's new in the dashboard, routing and docs. - [Retries, queueing and provider usage](https://relayrunner.dev/docs/changelog/retries-queueing-and-provider-usage.md): The Router retries jobs whose runner failed them, waits for busy machines and skips stuck providers, and the dashboard syncs real usage from your providers. - [Route a repo from the dashboard](https://relayrunner.dev/docs/changelog/route-a-repo.md): Step through your repos on the Router page, pick each repo's jobs and sizes, and hand the change to your coding agent. - [Clearer run times and job sizes for members](https://relayrunner.dev/docs/changelog/run-times.md): Read one workflow's run times on History, see whether Runners is current, and let members size jobs in repos they can push to. - [Usual times, job history and the Mac queue](https://relayrunner.dev/docs/changelog/usual-times-and-mac-queue.md): See how long each job usually takes and has left, list a machine's jobs with relayrunner history, and see what's waiting in RelayRunner for Mac.