Skip to content
relayrunner
Sign in Get started Open dashboard

Install the CLI

Getting the relayrunner CLI onto a machine, and signing it in.

View as Markdown For AI agents

The relayrunner CLI connects a machine to your workspaces and routes a repo’s jobs. It runs on macOS and Linux with Node.js 22 or newer. Windows isn’t supported yet.

Install

Section titled “Install”

Run it with npx, with nothing to install:

Terminal window
npx relayrunner connect

Or install it globally:

Terminal window
npm install --global relayrunner
relayrunner --help

Sign in

Section titled “Sign in”

There are two ways to sign a machine in. Both open the dashboard, where you sign in with GitHub and name the machine. There’s no workspace to pick: the machine is in all of yours.

  • relayrunner connect signs in and puts the machine online in one go. Use this on a machine you’ll run jobs on now.
  • relayrunner login signs in and exits, without putting the machine online. Coding agents use this, since they can’t keep connect running after their session ends.

Check who the machine is signed in as with relayrunner whoami.

Keep it running

Section titled “Keep it running”

connect is the on/off switch. Leave it open in a terminal tab while you want the machine to take jobs. It reconnects on its own if the network drops.

To stop taking new jobs without going offline, run relayrunner pause, or press p in the connect terminal. relayrunner resume undoes it.

Update

Section titled “Update”

npx relayrunner always fetches the latest version. For a global install, run npm install --global relayrunner@latest.

connect installs GitHub’s latest runner each time it starts. GitHub stops sending jobs to a runner about 30 days after a newer one comes out, so restart connect now and then if you leave it open for weeks. The Runners page says when a machine’s runner needs an update.

See the CLI reference for every command and flag.