# 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.app/docs/get-started/agents. 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.app/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.app/openapi.json (https://relayrunner.app/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.app/llms-full.txt

## Tools

- [MCP server](https://relayrunner.app/docs/reference/mcp.md): https://agents.relayrunner.app/mcp, Streamable HTTP with OAuth sign-in. Discovery: https://relayrunner.app/.well-known/ai-catalog.json
- [API](https://relayrunner.app/docs/reference/api.md): the read-only API behind the MCP server, for your own OAuth clients, described by https://relayrunner.app/openapi.json
- [CLI](https://relayrunner.app/docs/reference/cli.md): the `relayrunner` npm package, https://www.npmjs.com/package/relayrunner
- [Source code](https://github.com/relayrunner/relayrunner): the GitHub repository

## Solutions

- [Routing](https://relayrunner.app/solutions/routing): Change where jobs run from the dashboard, without editing your workflows.
- [Your Mac as a runner](https://relayrunner.app/solutions/mac-runner): Run jobs on your Mac, each in a fresh Linux VM.
- [CI surges](https://relayrunner.app/solutions/ci-surges): Keep CI fast when coding agents and teammates push all day.

## Integrations

- [Blacksmith](https://relayrunner.app/integrations/blacksmith): Blacksmith runs GitHub Actions jobs on its own machines, under your Blacksmith account.
- [Depot](https://relayrunner.app/integrations/depot): Depot runs GitHub Actions jobs on its own machines, under your Depot account.
- [Namespace](https://relayrunner.app/integrations/namespace): Namespace runs GitHub Actions jobs on runners sized by profile, under your Namespace account.
- [WarpBuild](https://relayrunner.app/integrations/warpbuild): WarpBuild runs GitHub Actions jobs on its own machines, under your WarpBuild account.
- [Ubicloud](https://relayrunner.app/integrations/ubicloud): Ubicloud runs GitHub Actions jobs on its own machines, under your Ubicloud account.
- [RunsOn](https://relayrunner.app/integrations/runs-on): RunsOn starts a runner for each job in your own AWS account.
- [GitHub](https://relayrunner.app/integrations/github): GitHub-hosted runners work in every repository with nothing to set up.

## Pages

- [Changelog](https://relayrunner.app/docs/changelog.md): What's new in RelayRunner and the CLI.
- [CLI changelog](https://relayrunner.app/docs/changelog/cli.md): What's new in each release of the relayrunner CLI.
- [CI traces in your observability tool](https://relayrunner.app/docs/changelog/opentelemetry-traces.md): Send every workflow run to Honeycomb, Grafana, Axiom or any OpenTelemetry tool as a trace.
- [Platform changelog](https://relayrunner.app/docs/changelog/platform.md): What's new in the dashboard, routing and docs.
- [Retries, queueing and provider usage](https://relayrunner.app/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.
- [Optimized checks](https://relayrunner.app/docs/concepts/optimized-checks.md): Simple checks that run with no runner and no billed minutes.
- [Principles](https://relayrunner.app/docs/concepts/principles.md): The rules routing follows.
- [Routing](https://relayrunner.app/docs/concepts/routing.md): How a GitHub Actions job opts in to routing, and how the relay picks its runner.
- [Runner order](https://relayrunner.app/docs/concepts/runner-order.md): The list a workspace tries runners in, and how to change it.
- [Add a provider](https://relayrunner.app/docs/contribute/add-provider.md): Teach RelayRunner to recognize another runner service, with a pull request.
- [Feedback](https://relayrunner.app/docs/contribute/feedback.md): How to report a problem or ask for something.
- [Activity and history](https://relayrunner.app/docs/dashboard/activity.md): Where each job ran, why it ran there, and how long it waited.
- [Performance](https://relayrunner.app/docs/dashboard/performance.md): How long your workflows and jobs usually take, and which runner suits each job.
- [Remove RelayRunner](https://relayrunner.app/docs/dashboard/remove.md): Switching jobs back, disconnecting machines and uninstalling the GitHub App.
- [Signals](https://relayrunner.app/docs/dashboard/signals.md): What makes your CI slow, costly or busier than it needs to be, and which workflows it affects.
- [Telemetry](https://relayrunner.app/docs/dashboard/telemetry.md): Send every workflow run to your observability tool as an OpenTelemetry trace.
- [Usage and savings](https://relayrunner.app/docs/dashboard/usage.md): Minutes, cost estimates, and what optimized checks saved.
- [Workspaces and members](https://relayrunner.app/docs/dashboard/workspaces.md): One workspace per GitHub install, its roles, and where members come from.
- [Set up with an agent](https://relayrunner.app/docs/get-started/agents.md): Letting a coding agent set up RelayRunner and route your jobs for you.
- [How it works with GitHub Actions](https://relayrunner.app/docs/get-started/github-actions.md): What changes in your GitHub Actions workflows, what stays the same, and which jobs you can route.
- [Install the CLI](https://relayrunner.app/docs/get-started/install.md): Getting the relayrunner CLI onto a machine, and signing it in.
- [Move your workflows over](https://relayrunner.app/docs/get-started/move-over.md): What relayrunner init changes in your GitHub Actions workflows, and which jobs it leaves alone.
- [Route GitHub Actions jobs to any runner](https://relayrunner.app/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.
- [Quickstart](https://relayrunner.app/docs/get-started/quickstart.md): Go from sign-up to a green GitHub Actions job on your own machine.
- [Keep up with coding agents](https://relayrunner.app/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.
- [Run CI on your laptop while you work](https://relayrunner.app/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.app/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.
- [Spend controls](https://relayrunner.app/docs/guides/spend-controls.md): Use your included GitHub minutes first, then switch to your own machines before you pay overage.
- [Share your team's machines](https://relayrunner.app/docs/guides/team-machines.md): Pool the team's spare computers so anyone's jobs can use them.
- [RelayRunner API](https://relayrunner.app/docs/reference/api.md): Read your workspace's runners, runs, routing and usage over HTTP.
- [CLI](https://relayrunner.app/docs/reference/cli.md): Every relayrunner command and flag.
- [Errors](https://relayrunner.app/docs/reference/errors.md): The error codes the API returns, and what each one means.
- [FAQ](https://relayrunner.app/docs/reference/faq.md): Common questions about RelayRunner.
- [GitHub App](https://relayrunner.app/docs/reference/github-app.md): What the RelayRunner GitHub App can do, and why it asks for each permission.
- [Runner labels](https://relayrunner.app/docs/reference/labels.md): Every runs-on label RelayRunner uses or answers, and what it means.
- [MCP server](https://relayrunner.app/docs/reference/mcp.md): Let AI agents read your workspace's runners, runs and usage.
- [Data and privacy](https://relayrunner.app/docs/reference/privacy.md): What RelayRunner sees and stores about your jobs, repos and machines.
- [relay.yml inputs](https://relayrunner.app/docs/reference/relay-inputs.md): Every input and output of the relay, a reusable GitHub Actions workflow.
- [Repo config](https://relayrunner.app/docs/reference/repo-config.md): The relayrunner.yml file, which sets a repo's checks and retries.
- [Security](https://relayrunner.app/docs/reference/security.md): What RelayRunner can and can't do with your code and machines.
- [Troubleshooting](https://relayrunner.app/docs/reference/troubleshooting.md): Common problems and how to fix them.
- [GitHub-hosted](https://relayrunner.app/docs/runners/github.md): Using GitHub's own runners as a provider, and keeping an eye on minutes.
- [Hosted providers](https://relayrunner.app/docs/runners/hosted.md): Routing jobs to Blacksmith, Depot, Namespace, WarpBuild, Ubicloud and RunsOn.
- [Providers](https://relayrunner.app/docs/runners/providers.md): Where you can route jobs, and the runner services the dashboard recognizes.
- [Your machines](https://relayrunner.app/docs/runners/self-hosted.md): Turn computers you own into GitHub Actions runners with the CLI.