Skip to content
relayrunner
Sign in Get started Open dashboard

Run CI on your laptop while you work

For a solo developer who wants CI on their own computer while they're working, and back on GitHub when the lid closes.

View as Markdown For AI agents

Your laptop is idle most of the time you’re coding, and it’s usually faster than a 2-core hosted runner. This guide runs your CI there while you work, and on GitHub the rest of the time, with nothing to switch.

1. Connect the laptop

Section titled “1. Connect the laptop”
Terminal window
npx relayrunner connect

Sign up and install the GitHub App when it asks. Leave connect running in a terminal tab.

2. Route your jobs

Section titled “2. Route your jobs”

In your repo’s checkout:

Terminal window
npx relayrunner init

Pick the jobs to route. Each keeps its old label, such as ubuntu-latest, as the fallback. Commit and push.

3. Check the runner order

Section titled “3. Check the runner order”

On the dashboard’s Router page, a new workspace starts with:

  1. Self-hosted
  2. GitHub-hosted

That’s what you want: the laptop when it’s free, GitHub otherwise.

What happens day to day

Section titled “What happens day to day”
  • While you work, jobs you push run on the laptop. The connect terminal shows each one.
  • When the laptop is busy with as many jobs as it runs at once, the next one goes to GitHub, so a long test run never blocks a quick lint.
  • When the lid closes or you stop connect, jobs go to GitHub, with nothing to change.
  • A job running at that moment stops with the laptop. Use Re-run all jobs to send it to GitHub, or Re-run failed jobs to run it on the laptop again once it’s back. With automatic retries on, the Router re-runs it for you.

To keep the laptop free for a while, without going offline, press p in the connect terminal or run relayrunner pause.

Keep it to your own jobs

Section titled “Keep it to your own jobs”

A new machine only runs jobs you started, so a teammate’s push or a bot never lands on your laptop. Leave it that way for a personal machine. See Your machines.

Linux jobs on a Mac

Section titled “Linux jobs on a Mac”

On a Mac with Apple silicon, each job runs in its own Linux VM, so jobs written for ubuntu-latest run as they are: apt, services: and container: all work, and the job can’t read your files. See Isolated jobs on a Mac.

On an Intel Mac, jobs run on macOS. Most Node, Python, Go or Rust jobs run fine there. Jobs that install Linux packages with apt, or use services: or container:, need Linux or Docker. init warns about these. Give them machine: Linux instead, or leave them on GitHub.