> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Runner images

> The Linux and macOS operating systems, toolchains, and preinstalled tools on Darkbloom runners, and how a job adds what the image lacks.

Each Darkbloom runner boots a fixed image with a fixed set of tools. A job takes
its space from its own writable scratch disk; the image's root is read-only.
Versions below are the ones the images pin.

## Linux

| Component | Version or detail |
| - | - |
| Operating system | Ubuntu 24.04 |
| Kernel | Linux 6.12.28 with dm-crypt |
| GitHub Actions runner | 2.338.2 |
| Python | 3.12.3, with `python3-venv` and `pip` 24.0 |
| Git | 2.51.1 |
| Make | 4.3 |
| jq | 1.7.1 |
| curl | 8.5.0 |
| OpenSSL | 3.0.13 |
| zstd | 1.5.5 |
| awk | GNU Awk 5.2.1 (`gawk`, also `nawk`) |
| keyctl | keyutils 1.6.3 |
| Other base tools | GNU coreutils, procps, tar, gzip, xz, unzip |

The image also carries the libraries Playwright's Chromium loads, and
Liberation Sans, which fontconfig gives Chromium for Arial. It does not carry
Chromium itself: a job downloads the browser its lockfile names.

A Linux job runs as UID/GID 1000 with `HOME` set to `/home/runner`. Its root is
read-only and the runner runs with `no_new_privs`, so a job has no `sudo` and no
`apt`. Its writes go to a 30 GiB encrypted scratch disk: checkouts, build
outputs, the tool cache, `RUNNER_TEMP`, home caches (npm, pip, cargo, ...),
`/tmp` and `/var/tmp`.

## macOS

| Component | Version or detail |
| - | - |
| Operating system | macOS 27.2 |
| Xcode | 27.2 (27B52), macOS SDK 27.2, Swift 6.4.2 |
| Homebrew | Installed |
| Python | 3.12.10 in the runner tool cache |
| CMake | 3.31.12, with `cmake`, `ctest` and `cpack` on `PATH` |
| zstd | 1.5.7, with `unzstd`, `zstdmt` and `zstdcat` on `PATH` |
| metal-cpp | Apple's metal-cpp 26 archive |
| GitHub Actions runner | 2.338.2 |

Homebrew comes first on the job's `PATH`, before the system's directories;
`cmake` and `zstd` come after them. The zstd and metal-cpp files are there
because jobs and their actions call them without installing them:
`actions/cache` compresses with zstd when `zstd --quiet --version` answers, and
MLX's CMake build can use the pinned metal-cpp archive instead of downloading
it.

A macOS job has a Metal GPU: the VM's paravirtualized device. MLX, MPS and
simdgroup matrices run at the host GPU's speed, but the device reports its
architecture as `air64_v27`, never the host's `applegpu_*` name. A check that
compares the architecture a library picks with the host's name fails in every
macOS VM, Blacksmith's included.

## Add tools a job needs

* **Linux:** install into the scratch disk (the checkout, `HOME`,
  `RUNNER_TEMP` or a tool cache) or use an action such as `actions/setup-*`
  that does. There is no `apt` and no `sudo`. A tool the image should provide
  for every job is an image change: ask your Darkbloom contact.
* **macOS:** `brew install` works for the job, and Homebrew comes first on
  `PATH`. A tool you install exists only for that job's VM.
* **Both:** a tool you download needs a host Darkbloom approved for your
  repository ([caching and network](https://docs.darkbloom.dev/ci/caching-and-network.md)). Pin the version
  you download; an image update can change a tool's version.
* **Caches:** `actions/cache` and the tools built on it work unchanged. See
  [caching and network](https://docs.darkbloom.dev/ci/caching-and-network.md) for where a cache is stored
  and when a job misses it.

## When a tool is missing

A job that passes on a GitHub-hosted runner can still fail here if it relies on
something the image does not carry. Check the tables above first, then the
job's network access: a download from an unapproved host fails the step.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.