feat: add digest-pinned OCI image management

Amp-Thread-ID: https://ampcode.com/threads/T-019c7d62-3f6b-7188-94cc-63e3d4f1cb10

Author: lox

README.md

@@ -12,6 +12,7 @@ It is built for this lifecycle:
 ## What It Does
 
 - Compiles repository policy from `cleanroom.yaml`
+- Requires digest-pinned sandbox base images via `sandbox.image.ref`
 - Enforces deny-by-default egress (`host:port` allow rules)
 - Runs commands in a Firecracker microVM via guest agent
 - Returns exit code + stdout/stderr over API
@@ -101,6 +102,15 @@ curl --silent --show-error \
 cleanroom exec -- pi run "implement the requested refactor"
 ```
 
+Image lifecycle commands:
+
+```bash
+cleanroom image pull ghcr.io/buildkite/cleanroom-base/alpine@sha256:...
+cleanroom image ls
+cleanroom image rm sha256:...
+cleanroom image import ghcr.io/buildkite/cleanroom-base/alpine@sha256:... ./rootfs.tar.gz
+```
+
 ## API Contract (Current)
 
 ### `POST /v1/cleanrooms/launch`
@@ -141,6 +151,8 @@ Response fields:
 - `stderr`
 - `run_dir`
 - `plan_path`
+- `image_ref`
+- `image_digest`
 
 ### `POST /v1/cleanrooms/terminate`
 
@@ -166,6 +178,8 @@ Minimal example:
 ```yaml
 version: 1
 sandbox:
+  image:
+    ref: ghcr.io/buildkite/cleanroom-base/alpine@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
   network:
     default: deny
     allow:
@@ -187,13 +201,14 @@ backends:
   firecracker:
     binary_path: firecracker
     kernel_image: /opt/cleanroom/vmlinux
-    rootfs: /opt/cleanroom/rootfs.ext4
     vcpus: 2
     memory_mib: 1024
     guest_cid: 3
     launch_seconds: 30
 ```
 
+The Firecracker adapter resolves `sandbox.image.ref` through the local image manager and caches materialised ext4 files under XDG cache paths.
+
 ## Isolation Model
 
 - Workload runs in a Firecracker microVM
@@ -235,7 +250,8 @@ cleanroom status --run-id <run-id>
 - Linux host
 - `/dev/kvm` available and writable
 - Firecracker binary installed
-- Kernel image + rootfs image configured
+- Kernel image configured
+- `mkfs.ext4` installed (used to materialise OCI layers into ext4 cache artifacts)
 - `sudo -n` access for `ip`, `iptables`, and `sysctl` (network setup/cleanup)
 
 ## References

cleanroom.yaml

@@ -1,5 +1,7 @@
 version: 1
 sandbox:
+  image:
+    ref: ghcr.io/buildkite/cleanroom-base/alpine@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
   network:
     default: deny
     allow:

examples/basic/README.md

@@ -14,7 +14,7 @@ The CLI should be available in `GOBIN` (or `GOPATH/bin`).
 
 ## Files
 
-- `cleanroom.yaml`: deny-by-default network policy with one allowed host.
+- `cleanroom.yaml`: digest-pinned sandbox image ref plus a deny-by-default network policy with one allowed host.
 - `marker.sh`: command that writes a local marker file.
 - `cleanup.sh`: removes marker files created during testing.
 
@@ -54,12 +54,23 @@ Expected: marker file exists and contains a timestamp.
 
 ## Optional: launched backend path
 
-Launched execution requires runtime config (`~/.config/cleanroom/config.yaml`) with Firecracker `kernel_image` and `rootfs`, plus a rootfs prepared with `cleanroom-guest-agent` boot hook.
+Launched execution requires runtime config (`~/.config/cleanroom/config.yaml`) with Firecracker `kernel_image`, plus a digest-pinned `sandbox.image.ref` in policy.
+
+Prewarm image cache (optional):
+
+```bash
+cleanroom image pull ghcr.io/buildkite/cleanroom-base/alpine@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+Or import a local tarball into the cache:
 
 ```bash
-sudo ../../scripts/create-rootfs-image.sh
-../../scripts/prepare-firecracker-image.sh
+cleanroom image import ghcr.io/buildkite/cleanroom-base/alpine@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef ./rootfs.tar.gz
+```
 
+Then run:
+
+```bash
 cleanroom exec -- ./marker.sh
 ls -la .marker-created
 ```

examples/basic/cleanroom.yaml

@@ -1,5 +1,7 @@
 version: 1
 sandbox:
+  image:
+    ref: ghcr.io/buildkite/cleanroom-base/alpine@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
   network:
     default: deny
     allow:

go.mod

@@ -8,12 +8,14 @@ require (
 	github.com/charmbracelet/log v0.4.2
 	github.com/creack/pty v1.1.24
 	github.com/firecracker-microvm/firecracker-go-sdk v1.0.0
+	github.com/google/go-containerregistry v0.20.2
 	github.com/mdlayher/vsock v1.2.1
 	golang.org/x/net v0.38.0
 	golang.org/x/sys v0.32.0
 	golang.org/x/term v0.31.0
 	google.golang.org/protobuf v1.36.10
 	gopkg.in/yaml.v3 v3.0.1
+	modernc.org/sqlite v1.33.1
 	tailscale.com v1.80.3
 )
 
@@ -43,9 +45,14 @@ require (
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/coder/websocket v1.8.12 // indirect
+	github.com/containerd/stargz-snapshotter/estargz v0.16.3 // indirect
 	github.com/coreos/go-iptables v0.7.1-0.20240112124308-65c67c9f46e6 // indirect
 	github.com/dblohm7/wingoes v0.0.0-20240119213807-a09d6be7affa // indirect
 	github.com/digitalocean/go-smbios v0.0.0-20180907143718-390a4f403a8e // indirect
+	github.com/docker/cli v27.4.1+incompatible // indirect
+	github.com/docker/distribution v2.8.3+incompatible // indirect
+	github.com/docker/docker-credential-helpers v0.8.2 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/fxamacker/cbor/v2 v2.7.0 // indirect
 	github.com/gaissmai/bart v0.11.1 // indirect
 	github.com/go-json-experiment/json v0.0.0-20250103232110-6a9a0fde9288 // indirect
@@ -59,6 +66,7 @@ require (
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/csrf v1.7.3-0.20250123201450-9dd6af1f6d30 // indirect
 	github.com/gorilla/securecookie v1.1.2 // indirect
+	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
 	github.com/hdevalence/ed25519consensus v0.2.0 // indirect
 	github.com/illarion/gonotify/v2 v2.0.3 // indirect
 	github.com/insomniacslk/dhcp v0.0.0-20231206064809-8c70d406f6d2 // indirect
@@ -74,10 +82,16 @@ require (
 	github.com/mdlayher/sdnotify v1.0.0 // indirect
 	github.com/mdlayher/socket v0.5.0 // indirect
 	github.com/miekg/dns v1.1.58 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/mitchellh/go-ps v1.0.0 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.0 // indirect
 	github.com/pierrec/lz4/v4 v4.1.21 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
 	github.com/prometheus-community/pro-bing v0.4.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/safchain/ethtool v0.3.0 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
@@ -91,6 +105,7 @@ require (
 	github.com/tailscale/web-client-prebuilt v0.0.0-20250124233751-d4cd19a26976 // indirect
 	github.com/tailscale/wireguard-go v0.0.0-20250107165329-0b8b35511f19 // indirect
 	github.com/u-root/uio v0.0.0-20240224005618-d2acac8f3701 // indirect
+	github.com/vbatts/tar-split v0.11.6 // indirect
 	github.com/vishvananda/netns v0.0.4 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
@@ -106,4 +121,10 @@ require (
 	golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect
 	golang.zx2c4.com/wireguard/windows v0.5.3 // indirect
 	gvisor.dev/gvisor v0.0.0-20240722211153-64c016c92987 // indirect
+	modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 // indirect
+	modernc.org/libc v1.55.3 // indirect
+	modernc.org/mathutil v1.6.0 // indirect
+	modernc.org/memory v1.8.0 // indirect
+	modernc.org/strutil v1.2.0 // indirect
+	modernc.org/token v1.1.0 // indirect
 )