runner-host¶
Host GitHub Actions jobs for an org on a Mac, each in a throwaway Tart VM.
jb-runner-host image # build the clean image (once, and to upgrade)
jb-runner-host install # LaunchDaemon: run jobs from boot (uses sudo)
jb-runner-host status # daemon, VMs, and the org's registered runners
jb-runner-host uninstall # remove the daemon and any job VMs (uses sudo)
The script is src/just_bashit/runner-host.sh. It needs macOS on Apple
silicon, Tart, curl and jq.
Why a VM per job¶
A self-hosted runner gets no container and no fresh machine of its own, and
container: jobs are Linux-only. A runner on the bare host would run every
job as the account someone also uses for their own macOS testing.
So each job gets a fresh VM:
imageclones a Cirrus Labs macOS base image, pinned by digest, and installs a pinned actions/runner (checked against its SHA-256) and theJB_RUNNER_BREWpackages. It saves the result asjb-base.run, which the LaunchDaemon runs, loops: it mints a registration token, clonesjb-base, boots the clone headless, registers an--ephemeralrunner in it, runs exactly one job, and deletes the VM. A failed job still deletes its VM. VMs left behind by a crash or reboot are deleted whenrunstarts.
Two VMs run at once by default (JB_RUNNER_VMS), each with 4 cores and 6 GB.
Apple's licence allows two macOS VMs per Mac, so run refuses more than 2.
Two VMs leave a 10-core, 16 GB Mac about 2 cores and 4 GB of its own.
Each VM is a slot with its own loop. It mints its own registration token, clones its own VM, and registers its own runner, with the same labels. One slot failing backs off only that slot. A SIGTERM stops every slot: each deletes its VM and deregisters its runner.
One Mac, two orgs¶
Each slot can serve a different org. JB_RUNNER_ORGS lists them in slot
order, so this gives slot 1 to just-buildit and slot 2 to doppler-dsp:
One org (the default, JB_RUNNER_ORG) serves every slot. Two orgs need two
slots, one each, since the two-VM limit still holds. The slot's org decides
its registration token, where its runner registers, and where it is
deregistered. status lists each org's runners, and uninstall and the
start-up sweep of leftover VMs deregister in every org.
Both orgs' runners carry the same labels. That is harmless: a runner registered to one org never sees another org's jobs.
The token¶
run needs a fine-grained personal access token per org. Its resource owner
is the org, with the Organization permission Self-hosted runners: Read and
write. A fine-grained token has one resource owner, so a second org needs a
token of its own.
| org | token file (mode 600) |
|---|---|
JB_RUNNER_ORG (just-buildit) |
~/.config/jb-runner/token |
| any other, e.g. doppler-dsp | ~/.config/jb-runner/token.doppler-dsp |
token.<org> sits beside JB_RUNNER_TOKEN_FILE, and wins for
JB_RUNNER_ORG too when it exists. Another org never falls back to the
plain token: that would send one org's token to another's API. run and
install check every org's token first, and refuse a missing one, one
another account can read, one owned by another user, or a symlink.
The token never enters a VM. It reaches curl as a header on stdin, so no
ps on the host can see it. Each VM gets only a short-lived registration
token, also on stdin.
Before it takes jobs from public repos¶
A fork PR on a self-hosted runner runs a stranger's code on your machine. Keep the org runner group's Allow public repositories setting off until every workflow keeps fork PRs on GitHub-hosted runners (just-buildit.github.io#203). Until then, the runner registers and sits idle.
That gate treats a label shaped like a GitHub-hosted image name (ubuntu-*,
macos-*, windows-*) as GitHub-hosted. So run and install refuse such a
label, after trimming spaces: a runner carrying macos-latest would take fork
jobs.
Network¶
A job can reach the internet and nothing private. Measured from inside a job VM on 2026-11-08 (Tart 2.41.1, Softnet 0.24.1):
| Target | Tart's default NAT | Softnet, as run boots it |
|---|---|---|
| This Mac, through the VM's gateway (ssh, rapportd) | reachable | blocked |
| This Mac's LAN address, the router | reachable | blocked |
| Tailnet nodes (100.64.0.0/10), ssh | reachable | blocked |
| The internet (github.com over HTTPS) | reachable | reachable |
Tart's default network NATs the VM through this Mac, so a job could reach
everything the Mac can. So every VM boots with --net-softnet-block over
the RFC 1918 ranges and 100.64.0.0/10 (JB_RUNNER_NET_BLOCK). Softnet already
drops other non-global IPv4. Blocking the private ranges also closes the
gateway, which is this Mac and picks a fresh private subnet each boot. That
gateway would otherwise answer DNS, so image sets the VM's resolvers to
JB_RUNNER_DNS (1.1.1.1, 8.8.8.8). The host has no IPv6, and a VM gets no
IPv6 route.
Softnet needs root to create the VM's network, so it is installed setuid root.
It drops privileges after setup. Tart runs whichever softnet is first on its
PATH, so run puts JB_RUNNER_SOFTNET (/usr/local/bin/softnet) first. A
softnet someone drops in ~/.local/bin is never used. run and image
refuse to start, rather than fall back to the open network, unless that file:
- is a real file (not a symlink), setuid, and owned by root;
- is writable by no group or other, and so is every directory above it. A
sticky root-owned directory such as
/tmpis allowed.
A setuid-root binary that anyone else can replace is a root escalation. Install a release pinned by its SHA-256, from cirruslabs/softnet:
Configuration¶
Every setting is an environment variable. --help lists them all. install
writes the values it was run with into the LaunchDaemon, so the daemon runs
the configuration you tested. Run install as the runner's user, not under
sudo: it calls sudo itself, and refuses to run as root.
VM and runner names carry the host's short name and the slot
(jb-job-<host>-s1-<time>), so
two Macs registering to one org never replace each other's runners. run and
image take a lock (JB_RUNNER_LOCK), so a manual run --once cannot sweep
the daemon's live VM, and image cannot replace the image under a clone. A
lock left by a killed process, or by one from before a reboot, is taken over.
Each job puts ~/.local/bin first in the runner's .path, after config.sh
writes it.
Nothing else is baked in for CI: workflows install uv and Python with their
usual setup actions, into the runner's tool cache.
JB_RUNNER_VERSION and JB_RUNNER_SHA256 pin actions/runner. Runners are
registered with --disableupdate, and GitHub stops sending jobs to a runner
more than 30 days behind the latest release. So re-pin and re-run image at
least monthly.
The daemon logs to ~/Library/Logs/jb-runner.log.