# Migrate from Blacksmith: the label map and what breaks

> Migrate from Blacksmith to another GitHub Actions runner: the label map by size, what replaces sticky disks and the Docker cache, and when to stay.

Source: https://latchkey.dev/learn/runners/migrate-from-blacksmith  
Updated: 2026-09-20

To migrate from Blacksmith is a one-line change per job and two things that are not: the sticky disks and the Docker layer cache, both of which are Blacksmith-specific actions that have to be swapped back before the label changes. Everything else carries over, including your `actions/cache` steps, because Blacksmith deliberately made the standard cache actions work against its own backend.

Blacksmith publishes what it sells, which makes this migration unusually checkable. Its runner documentation lists every label with the vCPU, memory and disk behind it: `blacksmith-2vcpu-ubuntu-2404` is 2 vCPU with 8 GB and 80 GB of disk, and the x64 line runs to 32 vCPU with 128 GB and 1.5 TB. Its ARM line carries 3 GB per core rather than 4, so the 2 vCPU ARM card is 6 GB, which matters when you map it onto something else.

Its pricing page lists $0.004 a minute for Ubuntu x64 at 2 vCPU, $0.0025 for ARM, $0.008 for Windows and $0.08 for a 6 vCPU macOS M4, with 3,000 free minutes a month on every card and Docker layer caching and sticky disks as add-ons at $0.50 per GB a month. The vendors that undercut it, and by how much, are priced in [Blacksmith alternatives](/learn/runners/blacksmith-alternatives).

One claim to handle carefully on the way out, because it changes what "cheaper" means: its documentation says Blacksmith runners are "exactly half the cost of GitHub's per minute", which is true of its ARM card against GitHub arm64 at $0.005 and not of its x64 card against GitHub x64 at $0.006, where the gap is a third.

## The label map, with the disk in it

Map on memory and disk, not on vCPU alone. Blacksmith grows the disk with the size, from 80 GB at 2 and 4 vCPU to 750 GB at 16; a Latchkey runner reports 43 GB free at both `latchkey-small` and `latchkey-medium`, measured on a real runner on 2026-09-20. A job that filled a 750 GB scratch disk has nowhere to land, and it will tell you so as [a no space left on device error](/learn/failures/no-space-left-on-device-github-actions) rather than as a helpful warning.

| Blacksmith label | What it is | Closest Latchkey label | What changes |
| --- | --- | --- | --- |
| `blacksmith-2vcpu-ubuntu-2404` | 2 vCPU, 8 GB, 80 GB disk | `latchkey-small` | Same cores and memory, 43 GB of disk instead of 80 |
| `blacksmith-4vcpu-ubuntu-2404` | 4 vCPU, 16 GB, 80 GB disk | `latchkey-medium` | Measured at 4 vCPU and 15.3 GB usable, 43 GB of disk |
| `blacksmith-8vcpu-ubuntu-2404` | 8 vCPU, 32 GB, 160 GB disk | `latchkey-large` | Same cores and memory, a quarter of the disk |
| `blacksmith-16vcpu-ubuntu-2404` | 16 vCPU, 64 GB, 750 GB disk | `latchkey-xlarge` | Same cores and memory, 6% of the disk |
| `blacksmith-32vcpu-ubuntu-2404` | 32 vCPU, 128 GB, 1.5 TB disk | None | Latchkey stops at 16 vCPU; this job stays or goes to Depot |
| `blacksmith-2vcpu-ubuntu-2404-arm` | 2 vCPU, 6 GB, 75 GB disk | None | No arm64 runner; these jobs go to Namespace, WarpBuild or GitHub |
| `blacksmith-6vcpu-macos-latest` | 6 vCPU, 24 GB, 150 GB disk | None | No macOS runner at any price; see the macOS destinations page |

> Windows maps the same way as macOS: `blacksmith-2vcpu-windows-2025` and its larger cards have no Latchkey equivalent, so a mixed pipeline ends up with two vendors. The macOS options are priced in [Cirrus CI alternatives for macOS](/learn/runners/cirrus-ci-alternatives-for-macos).

## The pre-flight checklist

Seven items. Two of them are Blacksmith-specific and are the reason this is not a pure label swap.

- **Labels.** Grep the workflow directory for `runs-on:.*blacksmith` to find the jobs. Check reusable workflows and composite actions too.
- **Blacksmith actions.** Grep for `useblacksmith/`. The Docker builder and build-push actions are not drop-in on another runner and have to go back to the `docker/` originals.
- **Sticky disks.** Run `blacksmith stickydisk list` with your repository and write down every key and size. Anything in that list is state your jobs expect to find warm.
- **Secrets.** Blacksmith needs none of yours, so this is only a check that nothing was set on the Blacksmith app rather than in repository secrets.
- **Cache keys.** They carry over untouched, because the standard cache actions were already doing the work. What changes is the allowance: 25 GB per repository each week on Blacksmith, 25 GB per repository on Latchkey, 10 GB with 7-day eviction on GitHub-hosted.
- **Matrix and concurrency.** Blacksmith documents unlimited concurrency with dedicated capacity. GitHub-hosted is 20 to 500 concurrent jobs by plan, and most third parties publish no ceiling, so check the destination before a wide matrix meets it.
- **Artifacts.** Unchanged. `actions/upload-artifact` and `download-artifact` are GitHub features and do not care which runner ran the job.

## The before and after

The label is one line. The Docker builder is the part that fails loudly if you forget it, because `useblacksmith/setup-docker-builder` has nothing to talk to once the job is not on Blacksmith.

```.github/workflows/ci.yml
jobs:
  build:
    # before
    # runs-on: blacksmith-4vcpu-ubuntu-2404
    # after
    runs-on: latchkey-medium
    steps:
      - uses: actions/checkout@v5
      - uses: docker/setup-buildx-action@v4     # was: useblacksmith/setup-docker-builder@v2
      - uses: docker/build-push-action@v7      # was: useblacksmith/build-push-action@v2
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:cache
          cache-to: type=registry,ref=user/app:cache,mode=max
```

## What replaces sticky disks and the layer cache

Nothing replaces them exactly, and it is worth understanding why before you decide the move is neutral. Blacksmith keeps the BuildKit builder's state, layers and cache mounts included, on a persistent disk next to the runner, so nothing is exported or imported between runs and `RUN --mount=type=cache` directories survive. Its own documentation makes the contrast: exported caches serialize layer blobs on every build and never include cache mount contents.

On any runner without that, you are back to exporting: a registry or GitHub Actions cache backend, which uploads and downloads the blob each run and leaves cache mounts cold. For dependency caches the swap is clean, because `actions/cache` was already the interface. For sticky disks holding a Bazel or Gradle cache, plan on the first runs being slower and on cache mounts no longer persisting. Blacksmith's own note on deletion is the useful mental model: the next job starts from an empty disk and repopulates it, the same as a cold cache.

## What the runner is on the other side

Measured rather than described, so you can size against it. This is `latchkey-medium`, the label the 4 vCPU Blacksmith card maps onto, recorded on 2026-09-20 in job `cli-940a5fd7`.

```latchkey run --no-context --size medium, job cli-940a5fd7
label=latchkey-medium
os=Ubuntu 24.04.4 LTS
arch=x86_64
kernel=6.17.0-1019-aws
vcpu=4
mem_total_mb=15617
disk_avail=43G
docker=Docker version 29.7.2, build a7dcaa6
utc=2026-09-20T11:01:09Z
```

> 15,617 MB is 15.3 GB usable against the 16 GB on the Blacksmith card, which is the usual gap between a published figure and what the kernel reports. The disk is the row to check: 43 GB free here against 80 GB on the Blacksmith 4 vCPU card.

## When staying on Blacksmith is right

Three cases, and the first one is real. If your critical path is a single-threaded compile, Blacksmith has the strongest published evidence of any vendor in this comparison: 4,357 on the Passmark single-thread test in RunsOn's cross-vendor suite, against 2,268 for GitHub-hosted, read on 2026-09-20 and not measured here. Its own claim is a 2x speedup and Firecracker microVMs booting in under 3 seconds.

The second is coverage: Windows and macOS cards, ARM at $0.0025, four regions including two in Europe. The third is the allowance: 3,000 free minutes a month on every card, with no plan fee to buy first, is the largest allowance you get for nothing here, and 25 GB of weekly cache per repository is 2.5 times what GitHub gives. If those cover most of what you run, the rate difference below is smaller than it looks.

## The short answer

Leaving on rate alone: Latchkey is $0.0025 a minute against $0.004 for Ubuntu x64, a 38% cut at every size, with 25 GB of cache per repository and 2,000 to 6,000 free minutes a month on a plan that starts at $5. Ubicloud is cheaper still at $0.0012. Neither has arm64, Windows or macOS.

Leaving because re-runs cost you more than minutes: that is the case Latchkey is built for, and the sticky-disk and Docker-cache work above is the price of the move. Staying: if the compile is the critical path, if you use the platform cards, or if 3,000 free minutes covers the month, Blacksmith is a good product and the migration is not free.

## FAQ

### How does Blacksmith speed up GitHub Actions?

By three published mechanisms: higher single-thread CPUs, which it describes as gaming-class hardware, ephemeral Firecracker microVMs that boot in under 3 seconds, and a colocated cache it says quadruples throughput to 400 MB/s. Independent evidence exists for the first: RunsOn's cross-vendor suite records 4,357 single-thread against 2,268 for GitHub-hosted, published by a competitor and not measured here.

### What replaces the Blacksmith Docker layer cache?

An exported cache, which is a different thing. Swap `useblacksmith/setup-docker-builder` and `useblacksmith/build-push-action` back to the `docker/` originals and add `cache-from` and `cache-to` against a registry or the GitHub Actions cache backend. Expect the first builds to be slower, and expect `RUN --mount=type=cache` directories to start cold, because exported caches do not carry them.

### What happens to my sticky disks when I leave Blacksmith?

They stop being reachable, and their contents were never portable. List them first with `blacksmith stickydisk list` so you know which jobs depended on warm state, then rebuild each one as an `actions/cache` step with a real key, accepting that the restore is now a download rather than a disk that was already there.

### How many free minutes would I lose by leaving Blacksmith?

3,000 a month, on every plan card, and it is the largest allowance here that arrives without a monthly fee: GitHub Free gives 2,000 and Ubicloud 1,250, and GitHub's larger allowances of 3,000 to 50,000 come with a paid plan. Latchkey includes 2,000 to 6,000 on plans from $5 a month. Namespace and WarpBuild publish no standing allowance at all.

## References

- [Blacksmith runners: every label with its vCPU, memory and disk, and the boot-time claims (verified 2026-09-20)](https://docs.blacksmith.sh/blacksmith-runners/overview)
- [Blacksmith Docker build caching: the builder actions and what an exported cache omits (verified 2026-09-20)](https://docs.blacksmith.sh/blacksmith-caching/docker-builds)
- [Blacksmith pricing: per-size rates, free minutes and the cache add-ons (verified 2026-09-20)](https://www.blacksmith.sh/pricing)
- [Latchkey pricing: runner sizes, rates and included minutes (verified 2026-09-20)](https://latchkey.dev/pricing)
- [RunsOn benchmarks: published single-thread scores across providers (verified 2026-09-20)](https://runs-on.com/benchmarks/github-actions-cpu-performance/)

---

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