RelayRunner docs: Route GitHub Actions jobs to any runner Page: https://relayrunner.app/docs/get-started/overview Markdown: https://relayrunner.app/docs/get-started/overview.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 (this page) - 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 - 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 --- # Route GitHub Actions jobs to any runner > RelayRunner routes each GitHub Actions job to the first runner in your list that can take it, from your own machines to hosted runners. RelayRunner is a router for GitHub Actions. You tell it which runners a job may use, and it sends each job to the first one in your list that can take it right now: your laptop when it's online and free, a self-hosted runner your org already has, a hosted provider such as Blacksmith or Depot, or GitHub's hosted runners. Your workflows stay the same. Checks keep their names, logs stay in GitHub, and you change where jobs go from the dashboard, not with a commit. ## Why use it - **Your minutes ran out.** Coding agents push all day and use up a plan's included minutes early in the month. Send jobs to a machine you already own first, and keep GitHub as the fallback. - **Your bill spiked.** Use your included minutes, then switch to your own machines before you pay overage. - **macOS builds cost 10x.** Run them on the Mac on your desk, and fall back to hosted Macs when it's asleep. - **One spare machine isn't enough.** A home server or old laptop is free, but jobs queue behind each other. It only gets a job when it's idle, and the rest go to hosted runners. ## How it fits together - **Workspace.** Your team in RelayRunner. Each one is a GitHub organization or personal account with the RelayRunner GitHub App installed, and its members come from GitHub. - **Runners.** Where jobs can run: machines you connect with the CLI, self-hosted runners you already have, hosted providers and GitHub-hosted runners. See [Providers](/docs/runners/providers). - **Relay job.** A small job you add in front of each job you want routed. It names the runners that job may use and finishes in about a second, with no runner and no billed minutes. See [Routing](/docs/concepts/routing). - **Runner order.** The order the workspace tries runners in, set on the dashboard's Router page. See [Runner order](/docs/concepts/runner-order). ```yaml jobs: relay-test: uses: relayrunner/actions/.github/workflows/relay.yml@v1 with: machine: self-hosted # any machine in your workspace github: ubuntu-latest # when no machine is free test: needs: relay-test runs-on: ${{ needs.relay-test.outputs.runner }} steps: - uses: actions/checkout@v4 - run: npm test ``` Each job on a machine gets a fresh one-job runner, so nothing is left behind between jobs. Public repositories never run on your machines. ## Next - [Quickstart](/docs/get-started/quickstart): a green job on your own machine in a few minutes. - [Principles](/docs/concepts/principles): the rules routing follows.