# Runner usage and free minutes

> How managed runner minutes are metered, what the free tier covers, where usage appears, and what happens when free minutes run out.

Source: https://latchkey.dev/documentation/runner-usage-and-free-minutes

## Summary

- Billed per minute, rounded up per job: small $0.0025 to xlarge $0.0200; custom runners at the xlarge rate.
- Free minutes reset on the 1st of each month (2,000/4,000/6,000 by plan); only overage is billed.
- One-off jobs from the Latchkey CLI or an agent meter identically, from the same free-minute pool; their spend shows as a **CLI Jobs** line on Cost Analysis.
- Warnings land at 80% and 100% either way: card-less workspaces block new jobs when exhausted, subscriptions keep running and meter the overage.

## How metering works

- Usage is billed **per minute, rounded up per job**. A 90-second job on `latchkey-small` is 2 minutes.
- Each size has its own rate: small $0.0025, medium $0.0050, large $0.0100, xlarge $0.0200 per minute. Custom-configuration runners bill at the xlarge rate.
- Only time your job actually holds the runner is billed; jobs are capped by the 4-hour runner lifetime.
- Self-healing carries no separate fee: extra runtime during a heal bills at the runner's standard per-minute rate.
- One-off jobs from the [Latchkey CLI](/documentation/latchkey-cli) or the MCP `run_job` tool meter the same way: same per-minute rates, same free-minute pool, rounded up per job. They default to a 30 minute timeout, extendable to 2 hours, and queue time is never billed.
- Overage lands as metered line items on the same monthly Stripe invoice as your plan.

Rounding happens per job, not per month, which matters when jobs are short: a 61-second job bills as 2 minutes, so a workflow that fans out into many one-minute jobs consumes minutes noticeably faster than its total wall-clock time suggests. If that ever becomes visible on your gauge, consolidating very short jobs is the lever.

## The free tier

| Plan | Free runner minutes per month |
| --- | --- |
| Developer | 2,000 |
| Launch | 4,000 |
| Scale | 6,000 |
| Enterprise | Custom |

Free minutes reset on the first of each calendar month. Minutes within the free tier cost nothing; only usage beyond it is billed at the per-minute rates.

## A worked example

The numbers below are illustrative; the rates and allowances are the real ones. Say a team on **Launch** (4,000 free minutes) runs 6,000 minutes of `latchkey-small` in a month:

| Line | Amount |
| --- | --- |
| Minutes metered on `latchkey-small` | 6,000 |
| Launch free tier | First 4,000 minutes at no cost |
| Billable minutes | 6,000 - 4,000 = 2,000 |
| Overage at $0.0025/min | 2,000 x $0.0025 = $5.00, as metered line items on the monthly invoice |

Size scales this linearly: the same 6,000 minutes on `latchkey-medium` ($0.0050/min) would come to $10.00 of overage, and on `latchkey-large` ($0.0100/min) to $20.00. The calculator below runs the same arithmetic with your own numbers.

## Estimate your cost

## Where to see usage

- The **Billing modal** shows a free-tier progress bar, this period's total and billable minutes, and the estimated runner cost so far.
- The **Latchkey Runners** page shows fleet-level cost, estimated savings versus GitHub-hosted, and free-tier consumption.
- The **Cost Analysis** page tracks Latchkey runner spend alongside your GitHub spend, including free-tier gauges for both.
- Jobs started from the [Latchkey CLI](/documentation/latchkey-cli) or an agent appear on [Cost Analysis](/documentation/cost-analysis) as their own **CLI Jobs** line; follow individual jobs from the CLI itself (`latchkey status`, `latchkey logs`).

## Running out of free minutes

- Workspaces without a card on file are warned at **80%** and again at **100%** of included minutes, at most once a day per threshold.
- **With a subscription on file:** you are warned at **80%** and again at **100%**, at most once per calendar month per threshold, and jobs keep running while the overage is metered to your invoice. There is no hard spend cap.
- **On a card-less trial:** once free minutes are exhausted, new managed-runner jobs are blocked until you subscribe. Blocked jobs stay queued on GitHub (no error in the GitHub UI) and a "Managed runner blocked" notification is sent.

### The timeline at a glance

Treat the 80% warning as the decision point rather than the 100% one: a fifth of the tier is still left, which is room to either trim usage (the [Cost Analysis](/documentation/cost-analysis) page shows where the spend is coming from) or accept the overage knowingly. With a subscription on file there is no hard spend cap, so accepting is a perfectly valid answer; it should just be a chosen one.

### If launches are blocked

1. **Confirm it is the free-minute gate** Blocked jobs sit in queued on GitHub with no error, and a "Managed runner blocked" notification is sent. The free-tier gauge (in the billing modal or on the Runners page) confirms the state: 100% used on a card-less trial.
2. **Subscribe to lift the block** New managed-runner jobs are blocked until you subscribe, so adding a subscription is the direct fix; with one on file, usage beyond the free tier simply meters to your invoice instead of blocking.
3. **Or bridge to the monthly reset** Free minutes reset on the first of the calendar month. Until then, urgent workflows can point back at GitHub-hosted labels, which keep working side by side with `latchkey-*` labels the whole time.

> ****
> If a job unexpectedly sits in queued and your workspace is on a trial, check the free-tier gauge first; it is the most common reason a runner launch is blocked.

### How are runner minutes metered?

Per minute, rounded up per job, from $0.0025 for small to $0.0200 for xlarge; custom runners meter at the xlarge rate. Rounding is per job, so many very short jobs cost more than the raw minutes suggest.

### When do free minutes reset?

On the first of each month, at 2,000, 4,000 or 6,000 minutes depending on plan. Only usage beyond the allowance is billed, so a month that stays inside the allowance costs nothing in runner minutes.

### Do CLI and agent jobs use the same free minutes?

Yes. One-off jobs started from the Latchkey CLI or an AI agent meter identically and draw from the same monthly pool. Their spend appears separately as a CLI Jobs line on Cost Analysis so you can see it without it being hidden inside workflow costs.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt