A planned, fully self-hosted CLI and daemon for managing GitHub Actions runners on a Mac. One local service manages Linux and macOS runner pools across organizations, with fixed capacity, demand-based scaling, safe draining, and recovery.
Status: design and implementation backlog. There is no runnable product or stability claim yet. Commands below describe the intended interface, not installed functionality. This project is independent of GitHub.
gh-runnerd init
gh-runnerd org add example-org
gh-runnerd pool add tests --org example-org --os linux --max 3
gh-runnerd autoscale tests --min 0 --max 3
gh-runnerd status
gh-runnerd logs tests --follow
gh-runnerd stop tests --drain- A native macOS ARM64 Go executable, with a CLI and separately supervised daemon.
- User-owned GitHub App authentication; no management SaaS, shared vendor private key, public inbound endpoint, or Kubernetes requirement.
- Linux runners through an explicit Docker Engine connection. Existing Docker Desktop or Lima engines can be used without changing the user's global Docker context.
- Native macOS process runners for explicitly trusted repositories only. A fresh working directory is not OS or credential isolation. macOS VM isolation is a later, separately gated provider.
- Multiple organizations, per-pool limits, and a shared host-wide capacity budget.
- One-job runners, durable state reconciliation, safe scale-down, structured diagnostics, and tests that exercise crashes and concurrent work.
Linux still needs a Linux kernel/runtime on macOS. The first release connects to an existing engine; it does not make Linux containers native macOS processes or provision a Kubernetes cluster.
GitHub Project provides Goals, Ready and Board views. All 21 issues carry a goal, model/effort, TDD cases, acceptance criteria and dependencies. Start with G01/G02/G03; the board does not dispatch agents automatically.
- Product and architecture plan
- Language and deployment decisions
- Authentication and trust boundaries
- TDD and release evidence
- Issue goals and agent execution
- Public CI and local checks
- Dependency and license inventory
- Published issue goals
- Ordered backlog
- Sources and unresolved experiments
The implementation target begins with one Apple Silicon Mac and two organizational installations. Organization examples in configuration are illustrative. No existing runner is migrated or removed by this repository.
MIT. Runtime dependencies and downloaded OS images keep their own licenses. No macOS image, restricted virtualization tool, credential, or third-party private key is distributed here.