build-initrd

Initrd Repack

just exec composes capsem-gate pack-initrd before boot. The gate stages the configured guest binaries, atomically repacks the host initrd, regenerates its manifest and hash aliases, and then materializes runtime config. capsem-init prefers these initrd copies over the rootfs copies.

The authoritative inventory and paths are [initrd] in config/gate.toml. Do not add a second list to a recipe, test, or gate module.

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-dns-proxy	UDP/TCP DNS-to-vsock relay
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-bench-rs	Rust guest benchmark helper
capsem-doctor	VM self-diagnostic suite (bash script)
capsem-bench	Guest benchmark driver (bash script)
capsem_bench/	Python benchmark support tree
diagnostics/	pytest test files for capsem-doctor

Adding a new guest binary

Update two authorities, then their behavior tests:

1. [initrd].binaries in config/gate.toml -- the repacker, static gate, build-chain test, and release asset rail all consume it.
2. guest/artifacts/capsem-init -- add the initrd-first deployment/fallback behavior if the new process is launched during boot.

Update this table and add the relevant unit, archive, and in-VM behavior tests.

When to use which build path

Changed	Command	Why
Guest binary source (Rust agent code)	just exec	Auto-repacks initrd with new binary
capsem-init script	just exec	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 [arch]	Baked into rootfs, not initrd
Runtime package set (config/docker/image/build.toml runtime_apt_packages)	just build-assets [arch]	Baked into the runtime rootfs asset
Application tools (AI CLIs, language toolchains)	an OCI image under images/	Not part of the runtime; see /build-images

Guest binary security

All guest binaries are deployed read-only:

• Rootfs: chmod 555 in Dockerfile template (rootfs mounted read-only)
• Initrd override: [initrd].binary_mode in the gate repacker 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. build_system/builder/gate/initrd.py:

1. Resolves the exact content-addressed Rust payload generation under the configured cache/target/build/linux-agent/<arch>/ tree. Source bytes, modes, paths, toolchain inputs, and the sealed builder image define the generation; checkout timestamps never do.
2. Unpacks the exact target into a temporary directory.
3. Replaces the config-owned binaries, files, trees, and init script at their configured modes.
4. Packs beside the target and uses AtomicReplace, preserving old hardlinks.
5. Regenerates the manifest and hash aliases whenever it mutates public assets.

The complete IronBank asset graph has a visible assets.pack-initrds frontier after both architecture lanes and before merge/boot. It repacks every architecture's private target. The CI-facing build-assets rootfs|all rail uses the same primitive before upload; kernel intentionally keeps its minimal initrd until the following rootfs step.

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 runtime rootfs asset
2. [initrd].binary_mode through the gate repacker -- mode on the initrd copy

The initrd copy wins at runtime because it overlays the rootfs. Keep both locations at 555 and prove the final archive with tests/capsem-build-chain/test_pack_initrd.py.