Architecture: How to build the Firecracker VM rootfs image for the sandbox...

Documentation for Sessions

🏗️ Architecture: How to build the Firecracker VM rootfs image for the sandbox...

Date: 2026-02-27
Time: 16:23:44 UTC
Session: gspace1-150.3
Agent: orchestrator
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to build the Firecracker VM rootfs image for the sandbox desktop?

Task: Build Firecracker VM rootfs image

🎯 Decision Made

Chosen:

Hybrid Dockerfile→ext4 export pipeline: build reproducibly in Docker (familiar CI tooling), then export container filesystem to ext4 image for Firecracker. Custom vm-init.sh as PID 1 parses kernel boot args for IP, resolution, VNC password, SSH pubkey.

Options Considered:

  1. Dockerfile→ext4 export (chosen)
  2. debootstrap + chroot (original plan)
  3. Packer automated builder
  4. cloud-init with systemd

💭 Reasoning

ROOT CAUSE: Original plan (Session 141) used mount -o loop + chroot for rootfs building — fragile, non-reproducible, requires manual package management. Dockerfile approach gives: (1) reproducible builds via docker build, (2) CI-friendly (can run in GitHub Actions), (3) familiar tooling, (4) layer caching for fast rebuilds. The ext4 conversion step (docker export + mkfs.ext4 + tar extract) is a one-time 2-minute operation. VM-init.sh reads kernel boot_args to configure networking, VNC, SSH at boot — eliminates need for cloud-init or systemd complexity. FUTURE RISK: If rootfs exceeds 4GB (unlikely with cleanup), increase IMAGE_SIZE_MB in build-rootfs.sh. EARLY WARNING: Monitor du -h rootfs.ext4 in CI.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation