version: "1.0.0" name: build-initrd description: Initrd repack and guest binary management for Capsem. Use when adding new guest binaries, modifying capsem-init, changing the initrd repack process, or understanding which binaries get injected at boot vs baked into the rootfs. Covers the fast iteration loop, binary list, and how to add new guest binaries.

Initrd Repack

just run automatically repacks the initrd before every boot. It cross-compiles guest binaries, injects them into the initrd, and capsem-init prefers initrd-bundled copies over rootfs copies at boot. This is the fast iteration loop (~10s) -- no full rootfs rebuild needed for guest binary changes.

Currently repacked binaries

Adding a new guest binary

Update three places:

1. `_pack-initrd` recipe in `justfile` -- add the cross-compile + copy step
2. `capsem-init` in `guest/artifacts/capsem-init` -- add initrd-bundled fallback logic (check /binary before rootfs path)
3. Binary list above -- add it to this skill

When to use which build path

Guest binary security

All guest binaries are deployed read-only:

• Rootfs: chmod 555 in Dockerfile template (rootfs mounted read-only)
• Initrd override: chmod 555 in _pack-initrd and capsem-init after copying to tmpfs
• Guest processes cannot modify these binaries at runtime

How initrd repack works

The initrd is a gzip+cpio archive. _pack-initrd in the justfile:

1. Builds Rust guest binaries via cross_compile_agent() (on macOS: container build; on Linux: native cargo) -- outputs to target/linux-agent/{arch}/
2. Creates a temp directory with the binaries + init script + diagnostics
3. Sets permissions (chmod 555 for binaries, 755 for init)
4. Packs as cpio+gzip, writes to assets/{arch}/initrd.img

At boot, capsem-init checks if a binary exists in the initrd bundle (/binary) before falling back to the rootfs path. This means initrd copies always take priority.

Lesson: permissions are set in TWO places

Guest binary permissions must be 555 (read+execute, no write). There are two independent places that set permissions and both must agree:

1. Dockerfile.rootfs.j2 -- chmod 555 when copying into the rootfs (baked into squashfs)
2. justfile `_pack-initrd` -- chmod when copying into the initrd (overlays rootfs at boot)

The initrd copy WINS at runtime because it overlays the rootfs. So even if the Dockerfile says 555, if the justfile says 755, the guest sees 755. When fixing permissions, always check both places. A rootfs rebuild (just build-assets) alone won't fix it if the initrd repack still sets the wrong mode.