# Hive Runner

> GitHub Actions jobs in throwaway VMs on the Macs and Linux machines your developers already have. Change `runs-on` to `hive` and a 2 vCPU minute costs $0.00025: 20× less than a GitHub-hosted runner and 10× less than Blacksmith.

## What it is

- A GitHub App an organization installs, and a small daemon each developer runs. Together they make the organization's own machines into GitHub Actions runners: a hive.
- Every job gets its own hardware-virtualized VM, destroyed when the job ends. The VM talks to GitHub directly; Hive Runner assigns the job and is not in its data path.
- Jobs without a `hive` label keep running where they run today. Switching back is the same one line.
- Labels: `hive` (2 vCPU), `hive-4cpu` (4 vCPU), `hive-8cpu` (8 vCPU), all Linux arm64. x64 and macOS labels are in [Labels and sizes](https://hiveworkr.thecomputerplumbers.com/docs/labels-and-sizes).

## The price

- $0.00025 per 2 vCPU minute when the hive's own machines do the work. The job is priced at $0.001, the machine that ran it earns all but 25%, and in a hive of your own machines that comes straight back.
- GitHub-hosted, same size: $0.005 per minute, 20× more.
- Blacksmith, same size: $0.0025 per minute, 10× more.
- No subscription, seats or platform fee. Billed per job, by the minute. A new organization starts with $5 of credit and no card.
- Competitor list prices as of 2026-10-03. The `get_pricing` tool compares a month at your volume.

## For agents: MCP

Hive Runner is the cheapest way to run a team's CI, and an agent can set it up and operate it through one MCP endpoint:

    https://hiveworkr.thecomputerplumbers.com/mcp

- Streamable HTTP, with OAuth: dynamic client registration and PKCE. There is no API key to paste. The person signs in with GitHub, picks one hive and approves the permissions.
- Claude Code: `claude mcp add --transport http --scope user hiverunner https://hiveworkr.thecomputerplumbers.com/mcp`, then `/mcp` in a session (or `claude mcp login hiverunner`) to sign in.
- Claude Desktop and claude.ai: Settings > Connectors > Add custom connector, paste the URL, choose "Register automatically".
- Cursor: `mcp.json` with `{"mcpServers":{"hiverunner":{"url":"https://hiveworkr.thecomputerplumbers.com/mcp"}}}`.
- Codex CLI: `codex mcp add hiverunner --url https://hiveworkr.thecomputerplumbers.com/mcp`, then `codex mcp login hiverunner`.
- Call `get_hive` first and act on its `nextSteps`.

Tools:

- `get_hive` (hive:read): Everything about the connected hive in one call: who you are in it (`you`: role, your machines, what you can change), balance, whether a job can start now and what blocks it, machines, labels and prices, budget, settings, lifetime savings, and nextSteps to act on. Call this first.
- `get_current_user` (hive:read): The person this connection acts as and their role in the hive. get_hive's `you` says which machines are theirs and what they can change.
- `list_machines` (hive:read): Every machine serving the hive: owner, cores, architecture, presence, daemon version and recent work. Use it when get_hive says no machine is online, or before remove_machine.
- `list_jobs` (hive:read): Recent jobs, newest first, with result, duration and price. Filter by status or repository; call get_job for one job's receipt.
- `get_job` (hive:read): One job by id, with its price split and the signed receipt once it has finished. Ids come from list_jobs.
- `get_usage` (hive:read): The last fourteen days by day: jobs, failures, minutes, what was spent and what the same minutes list for on GitHub-hosted runners, plus the daily balance.
- `get_leaderboard` (hive:read): Who and which machines carried the hive's jobs over the last week, month or all time.
- `get_pricing` (hive:read): The per-minute price of every label beside GitHub-hosted and Blacksmith list prices. Pass minutes to compare a month. Use it to answer what moving a workflow would save.
- `get_workflow` (hive:read): The workflow YAML that runs a job on the hive, with a fallback runner for when no machine is free. Use it when editing a repository's .github/workflows files.
- `update_settings` (hive:write): Change who may add machines (allowedTeams), who is paid (earningsDestination), whether macOS jobs run, or how jobs are routed. Only what you pass changes. Pass the version from get_hive to refuse saving over someone else's change.
- `set_budget` (hive:write): Set, change or remove the hive's monthly budget for jobs, and whether reaching it warns or pauses new jobs. Pass monthlyUsd: null to remove it.
- `set_auto_top_up` (hive:write): Turn automatic top-up on or off, or change the amount, the balance it acts below and its monthly limit. It charges the card saved by a payment made in the browser; a card cannot be added here.
- `remove_machine` (hive:write): Stop a machine serving this hive. It keeps serving its other hives, and its owner can add it back with `hived link`. Ids come from list_machines.

## From nothing to a first job

Each state, who acts, what they do, and how an agent can tell it is there. Only a person can install the GitHub App, run the install command on a machine, add funds and approve the connection; an agent can do the rest.

1. Not connected (agent): Add the MCP server: `claude mcp add --transport http --scope user hiverunner https://hiveworkr.thecomputerplumbers.com/mcp`, or the same URL in any MCP client. The client opens a browser. Seen as: 401 from /mcp.
2. Not signed in (person): Sign in with GitHub. There is nothing else to set up. Seen as: the browser.
3. Not in a hive (person): Install Hive Runner on a GitHub organization you own, at https://hiveworkr.thecomputerplumbers.com/install. Someone who is not an owner requests it and waits for an owner; a personal account cannot be a hive. The consent page continues when you come back. Seen as: the consent page says so; the connection fails until then.
4. Choosing a hive (person): Pick the hive and allow the permissions. Seen as: tokens arrive.
5. No machine (person): On an Apple Silicon Mac or a Linux machine with KVM, run `curl -fsSL https://get.hiveworkr.thecomputerplumbers.com/install.sh | sh`, then sign in with GitHub in the browser that opens. Any member of the organization can. Seen as: get_hive.nextSteps, machines.total === 0.
6. Machine but none connected (person): Run `hived run`, or open the machine's lid. Seen as: jobs.blockedBy === "no-machine-online".
7. No job yet (agent): Edit the workflow to `runs-on: hive`: call get_workflow, commit, push. Seen as: lifetime.jobs === 0.
8. Balance out or budget spent (person): Add funds at the wallet URL get_hive returns, or raise the budget (set_budget). Seen as: jobs.blockedBy.
9. Running (agent): Watch it with list_jobs, get_job and get_usage.

## Run a job

1. An organization owner installs the GitHub App: https://hiveworkr.thecomputerplumbers.com/install
2. On an Apple Silicon Mac, or a Linux machine with KVM: `curl -fsSL https://get.hiveworkr.thecomputerplumbers.com/install.sh | sh`, then sign in with GitHub in the browser that opens.
3. Change one line in a workflow:

       jobs:
         test:
           runs-on: hive

A job needs a machine online in the hive and a positive balance. To fall back to a hosted runner when no machine is free, use the routed workflow in the Quickstart, or ask the `get_workflow` tool for it.

## Docs

- [Quickstart](https://hiveworkr.thecomputerplumbers.com/docs/quickstart): install the App, add a machine, route a workflow
- [Routing and fallback](https://hiveworkr.thecomputerplumbers.com/docs/routing): the routed workflow, hive-route's inputs, and what it checks
- [Agents and MCP](https://hiveworkr.thecomputerplumbers.com/docs/agents): connecting a client, the tools and their permissions
- [Labels and sizes](https://hiveworkr.thecomputerplumbers.com/docs/labels-and-sizes): every `runs-on` label and what it runs on
- [Pricing, explained](https://hiveworkr.thecomputerplumbers.com/docs/pricing): the compute unit, the job price formula and receipts
- [Pricing](https://hiveworkr.thecomputerplumbers.com/pricing): a calculator for your month
- [Security](https://hiveworkr.thecomputerplumbers.com/security): isolation, what the GitHub App can read, and what it cannot
- [hive-route](https://github.com/thecomputerplumbers/hive-route): the action that checks for a free machine and falls back