SELECTION GUIDE

GitHub Actions runners without Kubernetes.

Runscaler is a Go autoscaler for self-hosted GitHub Actions runners. One manager process on each host starts a disposable Docker container or Tart VM for a job, then removes it when the job completes. The CLI executable is named runner.

Choose it when you want to use your own Docker host or Apple Silicon Mac and manage runner capacity through a config file and CLI. You remain responsible for host provisioning, runner images, credentials, and updates.

Autoscaling Docker runners on your own host

Use Docker when you have a Linux Docker host and want a fresh runner container for each trusted CI job. Runscaler long-polls GitHub's runner scale-set API, starts containers as jobs arrive, and can scale runner capacity to zero. No Kubernetes cluster or inbound webhook endpoint is required.

You need Docker API 1.49 or newer (Docker Engine 28.1+), a compatible runner image, GitHub App or PAT credentials, and enough host resources. Runscaler scales runners within the configured host capacity; it does not provision additional hosts.

  1. Build a Docker configuration with your GitHub URL and scale-set name.
  2. Follow the Linux quick start to install runner, save the config, add credentials locally, and install the service.
  3. Use your scale-set name in the workflow's runs-on field. For example, if you named it my-runners:
jobs:
  build:
    runs-on: my-runners
    steps:
      - run: echo "Running on a disposable runner"

Review Security & Isolation: the default Docker mode shares the host socket, granting jobs root-equivalent control over that daemon. Optional per-job DinD separates Docker state but uses a privileged sidecar and shares the host kernel. Run trusted code; do not expose these Docker runners to pull requests from public forks.

Ephemeral macOS runners on Apple Silicon

Use Tart for Xcode and other macOS workflows that need a fresh VM per job. Runscaler clones a prepared image, starts the VM, registers its GitHub runner, and removes the VM afterward. Optional warm pools prepare VMs ahead of work.

The host must be an Apple Silicon Mac with Tart installed. Select a compatible macOS/Xcode image and run the manager as a logged-in user through a LaunchAgent. macOS guests share a host-wide limit of two running VMs. Plan CPU, memory, and disk capacity for images, clones, and warm VMs.

Tart also supports prepared arm64 Linux guest images on the same Apple Silicon host. Linux guests do not consume the macOS VM permits; their capacity still depends on the host's resources. This does not provide a Tart backend on Linux hosts.

Start with the Tart prerequisites, then choose Tart in the config builder and follow the macOS quick start. Pin and maintain your image and GitHub runner version.

Runscaler, ARC, or manually managed runners?

Choose based on the infrastructure you want to operate. These are different deployment approaches, not a performance ranking.

Deployment and lifecycle responsibilities
ConsiderationRunscalerActions Runner Controller (ARC)Manually managed GitHub runner
Runs onYour Docker host or Apple Silicon Mac with TartA Kubernetes clusterA machine where you install the runner application
Runner lifecycleCreates and removes a container or VM per jobOrchestrates and scales runner podsYou arrange startup, scaling, and cleanup
OperationsA Go binary and TOML on each host; CLI diagnosticsKubernetes operator, Helm charts, and cluster resourcesRunner application and your service or scripts
Good fitExisting hosts; Docker or Tart; no Kubernetes requirementTeams already operating KubernetesFixed capacity or a custom lifecycle you maintain

GitHub describes ARC as a Kubernetes operator and recommends it for organizations with Kubernetes infrastructure and expertise. The self-hosted runner reference also describes the standalone scale-set client used to build custom autoscalers. Runscaler uses the official Go scale-set client; it is an independent project.

Consider another approach if you need managed CI with no host maintenance, automatic provisioning of cloud machines, centralized scheduling across hosts, or a managed multi-user web console. Runscaler manages the runners on each configured host. Hosts, images, and access policies remain yours to operate.

Frequently asked questions

Does Runscaler require Kubernetes or a public webhook?

No. It runs directly on your host and receives jobs through outbound HTTPS long-poll connections to GitHub's scale-set API. The host, runners, and VMs still need network access to GitHub and any services used by your jobs.

Does a fresh runner mean every job is fully isolated?

Each runner container or VM handles one job, but shared storage and Docker access affect isolation. Host socket mode grants jobs control of the host daemon. Per-job DinD separates daemon state, not the host kernel. Tart provides a VM boundary; network access, images, credentials, and explicit shared resources still need appropriate policies. See the security guide.

Can one process manage multiple repositories or organizations?

Yes. Configure multiple scale sets on the same host, including Docker and Tart where the host supports them. They share the manager's host capacity; this is not a cluster scheduler. See Configuration.

What about caching and disk usage?

Docker scale sets can opt into a host-local Actions cache receiver with supported runner images. Explicit shared volumes can retain files across jobs. Cache retention and disk cleanup require configuration; fresh runners do not imply that all host data is deleted. Read Host-local Actions cache and Caching.

Is Runscaler free, and how stable are upgrades?

Runscaler is MIT-licensed. Host costs, GitHub terms, and the licenses of Tart and runner images are separate. The project is pre-1.0: minor releases may change or remove interfaces. Review release notes and upgrade requirements before upgrading.

Ready to try it on your host?

Build your config ↗