Start here¶
Zoomies runs GitHub Actions jobs on machines you own or rent. It watches the queue, starts runners when they are needed, and removes each ephemeral runner after its job. You manage the fleet through a web UI, CLI or API.
New to self-hosted runners? Start with the fundamentals, then run your first job. Already running Zoomies? Use the task table below or go straight to advanced operations.
Choose a path¶
Evaluate Zoomies¶
Decide whether running your own fleet suits your workloads and your team.
- Should you self-host?: responsibilities and trade-offs.
- Try the local demo: explore a fixture fleet without GitHub credentials.
- Costs and alternatives: compare the whole cost of ownership.
Run your first job¶
Learn the few concepts needed to connect GitHub and run one trusted workflow.
- Fundamentals: controller, host, pool, runner and labels.
- Quick start: install, connect GitHub and verify a job.
- The web UI: find the job, its runner and the fleet's problems.
Grow and tune a fleet¶
Work from measured demand, add capacity and automate repeatable operations.
- Hosts and pools: placement and capacity.
- Advanced operations: sizing, performance, recovery and automation.
- Configuration, CLI and API: exact settings and interfaces.
Get help with jobs and workflows¶
Eli brings job context into a conversation from Ask Eli in the web UI. MCP connects your own assistant to diagnostics, measured runner sizing and, with separate consent, verified repository source. Use either to investigate failed or slow builds as well as fleet problems.
Start with assistant-led job troubleshooting. For a failed check on an existing PR, Eli repairs can publish a fix and watch CI after you configure and authorise repairs.
Find a task¶
| I want to… | Start with | Check that it worked |
|---|---|---|
| Install on one Linux machine | Quick start | A manually triggered job completes and its runner is removed. |
| Deploy the controller with a file | Docker Compose or PaaS | Claim the instance, connect GitHub and create a pool. |
| Add a machine | Hosts and pools | The host checks in and an eligible pool can place a runner there. |
| Use a private home or office host | Private hosts with Tailcat | The agent joins through the private connection and reports capacity. |
| Move existing workflows | Migration | Review a diff, run one migrated workflow, then expand. |
| Diagnose a queued job | A job stuck in the queue | Follow labels, installation access, host capacity and registration in order. |
| Speed up repeated builds | Persistent caches | Compare repeated runs on the same host; keep a cache-miss path working. |
| Allocate spare CPU or memory | Elastic CPU and elastic memory | Observe first, then compare run time and host pressure under representative load. |
| Route different job sizes | Size classes and automatic pools | Read shadow-mode decisions before enabling routing. |
| Create VMs when capacity is needed | Proxmox VE | Verify the template, join and workload before increasing limits. |
| Monitor the fleet | Metrics and problem codes | An authenticated scrape works and alerts reach the person who operates it. |
| Back up, restore or upgrade | Backup and restore, then upgrading | Verify the backup and rehearse recovery before relying on it. |
| Script fleet operations | CLI, API and automation contract | Use a scoped token and inspect errors; the automation contract is still proposed. |
| Diagnose a failed or slow build | Eli and MCP troubleshooting | Read the evidence, then compare a fix or optimisation against a baseline. |
| Repair a failed PR check | Eli PR repairs | Review readiness, the published diff and GitHub's resulting checks. |
| Connect my own assistant | MCP, Connect Claude or AI Context | Choose fleet access and repository source access deliberately. |
How to use these docs¶
The Quick start is a tutorial: follow it in order to reach a first successful job. Run your fleet contains task guides, usually starting in the UI and linking to CLI and API equivalents. Scale and tune covers optional features to adopt after the basic fleet works. Reference contains exact contracts, settings and architecture details to look up while working.
Use search for a setting such as scheduler.scale_up_delay, a problem code or
a command name. The long reference pages also have a table of contents for
jumping to one setting or route.
Before you commit workloads¶
Start with workflows you trust and a finite pool maximum. Container runners share a host kernel; a fresh runner is not a separate VM. The process backend runs directly on the host. Read security for the boundaries and platform qualification for the evidence behind support claims.
You own the host capacity, patching and recovery plan. Advanced operations gives you an order in which to put those in place.