1# Images and kernel
2
3A job runs in the image named by `ERMITE_RUNNER_IMAGE`.
4
5| Mode | Value | Contents |
6| --- | --- | --- |
7| `container` | OCI reference | Default `ermite-runner-ubuntu-26.04:latest` |
8| `vm` | Directory | `vmlinux` (`Image` on arm64) and `base.ext4`. Default `<state dir>/image` |
9
10Both come from `images/ubuntu-26.04/Dockerfile` (Ubuntu 26.04 LTS). The runner executable and Node.js are attached by the host. They are never part of the image.
11
12## Build
13
14```sh
15scripts/build-kernel.sh tmp/image   # vm only: builds the guest kernel
16scripts/build-image.sh tmp/image    # builds the OCI image and tmp/image/base.ext4
17```
18
19- `build-kernel.sh` downloads Linux 6.18 LTS from kernel.org and checks the tarball against the published sha256 sums. It needs `bc`, `flex`, `bison`, `pahole`, libelf and openssl headers.
20- `build-image.sh` needs Docker or Podman (rootless is fine) and e2fsprogs 1.47.1 or newer. No root is needed.
21- The OCI image is tagged `ermite-runner-ubuntu-26.04:latest`. Set `IMAGE_TAG` to change it.
22- The kernel config is `images/kernel/config-6.18` plus per-architecture fragments. The build fails if a listed option does not survive `olddefconfig`.
23- arm64 builds with `ARCH_NAME=arm64`.
24- `CONFIG_BINFMT_MISC` is built in and mounted by the guest init, so `docker/setup-qemu-action` can run foreign-architecture containers.
25
26## What the image must contain
27
28- User `runner`, uid and gid 1001, home `/home/runner`. Steps run as this user. Without it, steps run as root (test images only).
29- `/home/runner/work` and `/opt/hostedtoolcache`, owned by `runner`.
30- `bash` and `sh`. `python3` and a `python` command for `shell: python`.
31- `dockerd` and passwordless `sudo` for `runner`, for jobs that use Docker.
32- Common tools: git, curl, jq, build-essential, ca-certificates, tzdata, zip and unzip.
33
34`pwsh` is not in the image. A step that asks for it fails with `pwsh: command not found`.