kunchenguid/runner-up

What it does

runner-up runs GitHub Actions jobs on your own Linux, macOS and Windows machines instead of hosted runners. A coordinator talks to GitHub through runner scale sets, places each waiting job on a free machine, and starts a one-job runner over SSH inside a fresh Docker container, KVM VM, tart macOS clone, Apple container guest, Hyper-V VM or Windows account. Host places can also run jobs directly on the machine. Machines are divided into places, and places serve pools that workflows request in runs-on.

This suits teams with spare hardware or Macs who want to cut cloud CI spend while keeping jobs isolated from each other. It differs from a plain self-hosted runner, which reuses one registration, and from Kubernetes-based autoscaling, which requires a cluster; runner-up needs only SSH access to each machine.

Quick start

Install runner-up on the coordinator machine (Linux or macOS) and check the requirements first, including gh signed in as a repository admin and passwordless SSH to each worker.

# Serve one repository and define a Linux pool label.
runner-up init --repo you/app --pool my-linux

# Add a Docker worker (default on Linux).
runner-up machine add box --ssh ci@box

# Check the generated setup and start the coordinator.
runner-up check-config
runner-up serve

Then request the pool in a workflow:

jobs:
  build:
    runs-on: my-linux

By default each added machine serves every pool in the setup. If a Mac should only run macOS jobs, add a separate pool in the setup file and point the Mac's places at it, then run runner-up check-config again. The README documents the full setup file, service installation, Windows setup and update flow.

Requirements and limits

The coordinator runs on Linux or macOS and needs gh with admin access to each served repository (admin:org for organizations), key-based SSH to every worker, and the relevant provider tooling on each machine: Docker, KVM packages and a cloud image, tart on Apple silicon, or the experimental Apple container and Hyper-V providers. Windows workers need an administrator setup step.

Runner scale sets are still a GitHub preview, so upstream changes can break runner-up until it catches up. Docker places share the host kernel, and KVM places can reach services bound to the host's loopback; use KVM for less-trusted code and protect loopback services. Host places are not fresh between jobs. Fork pull requests are refused by default and should only be enabled if every fork PR is trusted. Hyper-V, Apple container, Windows account and setup-editing paths are marked experimental or only partially proven. Resource usage readings are sampled observations, not hard limits. The project is MIT licensed.

HotRepo's take

runner-up was recorded on the Go new-project list on 2026-11-04, gaining 18 stars in the captured window; the default branch project page shows about 133 stars and 6 forks. The repository has not appeared on the all-language daily rank. The pitch is concrete and the README documents isolation models, failure handling and trade-offs, but the young project's own status notes list several providers as not yet proven with real daily jobs, so the experimental paths deserve scrutiny before depending on them.