Quickstart
Go from sign-up to a green GitHub Actions job on your own machine.
You need a private GitHub repository, and a Mac or Linux computer with Node.js 22 or newer.
1. Connect your machine
Section titled “1. Connect your machine”In a terminal on the computer you want CI on, run:
npx relayrunner connectThe first run shows a code and opens the dashboard. Continue with GitHub to sign up and install the RelayRunner GitHub App on your organization or personal account in one trip. The install is your workspace. Then check the code matches and approve the machine.
Leave connect running. While it runs, the machine is online and takes jobs. Ctrl-C takes it offline.
2. Route a job
Section titled “2. Route a job”In another terminal, inside a checkout of your repository, run:
npx relayrunner initinit lists the repo’s jobs and lets you pick which to route. For each one it adds a relay job in front and points the job’s runs-on at the relay’s answer. The job’s old label, such as ubuntu-latest, becomes the fallback. It only edits .github/workflows/ and never commits. See Move your workflows over for what it changes and what it skips.
3. Push and watch
Section titled “3. Push and watch”Commit the change and push. In the workflow run on GitHub you’ll see relay-<job> / RelayRunner finish in about a second, then your job start. The terminal running connect shows the job as it runs.
Open Activity in the dashboard to see where the job ran and why. Stop connect, push again, and the same job runs on its old label instead.
- Runner order: choose what’s tried first.
- Run CI on your laptop while you work: the full laptop setup.
- Set up with an agent: let a coding agent do all of this.