build-initrd

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

Binary	What it does
capsem-init	PID 1 init script
capsem-pty-agent	PTY-over-vsock bridge agent
capsem-net-proxy	TCP-to-vsock relay for air-gapped HTTPS proxying
capsem-mcp-server	MCP stdio-to-vsock relay for AI agent tool access
capsem-sysutil	Guest suspend helper via vsock:5004; in-VM shutdown commands are disabled
capsem-doctor	VM self-diagnostic suite (bash script)
snapshots	Snapshot management CLI (Python, FastMCP client)
diagnostics/	pytest test files for capsem-doctor

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

Changed	Command	Why
Guest binary source (Rust agent code)	just run	Auto-repacks initrd with new binary
capsem-init script	just run	Init script is repacked into initrd
guest/artifacts/diagnostics/*.py	just exec "capsem-doctor"	Test files repacked into initrd
guest/artifacts/capsem-bashrc	just build-assets	Baked into rootfs, not initrd
Profile package/root/build inputs (config/profiles/<id>/)	just build-assets	Affects profile-derived rootfs rendering
Installed packages (apt, pip)	just build-assets	Baked into the profile rootfs asset

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 profile rootfs asset
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.