feat: add microvm kernel flavor for Firecracker sandboxes (CORE-79)

.github/workflows/build.yml

@@ -23,18 +23,29 @@ env:
 
 jobs:
   # ==========================================================================
-  # Build kernel for each architecture (native runners, no cross-compile).
+  # Build kernel for each architecture x flavor (native runners, no
+  # cross-compile). `system` boots the VZ/HV System VM; `microvm` boots
+  # Firecracker sandbox microVMs (arm64-only for now — Firecracker x86_64
+  # needs an ELF vmlinux and its own config).
   # ==========================================================================
   build-kernel:
-    name: Build Kernel (${{ matrix.arch }})
+    name: Build Kernel (${{ matrix.arch }}, ${{ matrix.flavor }})
     runs-on: ${{ matrix.runner }}
     strategy:
       matrix:
         include:
           - arch: arm64
+            flavor: system
+            artifact: kernel-arm64
             runner: ubuntu-24.04-arm
           - arch: x86_64
+            flavor: system
+            artifact: kernel-x86_64
             runner: ubuntu-24.04
+          - arch: arm64
+            flavor: microvm
+            artifact: microvm-kernel-arm64
+            runner: ubuntu-24.04-arm
 
     steps:
       - name: Checkout
@@ -56,22 +67,23 @@ jobs:
         run: |
           USE_DOCKER=0 \
           ARCH=${{ matrix.arch }} \
+          FLAVOR=${{ matrix.flavor }} \
           KERNEL_VERSION=${{ env.KERNEL_VERSION }} \
           OUTPUT_DIR="$(pwd)/output" \
           ./scripts/build-kernel.sh
 
       - name: Generate checksum
         run: |
           cd output
-          sha256sum "kernel-${{ matrix.arch }}" > "kernel-${{ matrix.arch }}.sha256"
+          sha256sum "${{ matrix.artifact }}" > "${{ matrix.artifact }}.sha256"
 
       - name: Upload kernel artifact
         uses: actions/upload-artifact@v4
         with:
-          name: kernel-${{ matrix.arch }}
+          name: ${{ matrix.artifact }}
           path: |
-            output/kernel-${{ matrix.arch }}
-            output/kernel-${{ matrix.arch }}.sha256
+            output/${{ matrix.artifact }}
+            output/${{ matrix.artifact }}.sha256
           retention-days: 14
 
   # ==========================================================================
@@ -92,11 +104,11 @@ jobs:
       - name: Prepare release files
         run: |
           mkdir -p release
-          for ARCH in arm64 x86_64; do
-            DIR="artifacts/kernel-$ARCH"
-            if [ -f "$DIR/kernel-$ARCH" ]; then
-              cp "$DIR/kernel-$ARCH" "release/kernel-$ARCH"
-              cp "$DIR/kernel-$ARCH.sha256" "release/kernel-$ARCH.sha256"
+          for NAME in kernel-arm64 kernel-x86_64 microvm-kernel-arm64; do
+            DIR="artifacts/$NAME"
+            if [ -f "$DIR/$NAME" ]; then
+              cp "$DIR/$NAME" "release/$NAME"
+              cp "$DIR/$NAME.sha256" "release/$NAME.sha256"
             fi
           done
           echo "=== Release files ==="
@@ -112,8 +124,9 @@ jobs:
             Self-compiled Linux kernel for ArcBox VMs (`CONFIG_MODULES=n`, all drivers built-in).
 
             ### Files
-            - `kernel-arm64` — ARM64 Image (Apple Silicon / ARM VMs)
-            - `kernel-x86_64` — x86_64 bzImage
+            - `kernel-arm64` — ARM64 Image, System VM (Apple Silicon / ARM VMs)
+            - `kernel-x86_64` — x86_64 bzImage, System VM
+            - `microvm-kernel-arm64` — ARM64 Image, Firecracker sandbox microVMs
           files: release/*
           draft: false
           prerelease: ${{ contains(github.ref_name, 'alpha') || contains(github.ref_name, 'beta') }}

CLAUDE.md

@@ -6,6 +6,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 `arcbox-kernel` provides optimized Linux kernel and initramfs builds for ArcBox VMs, targeting Apple Virtualization.framework (primary) and KVM (secondary).
 
+Two kernel **flavors** build from the same source — do not conflate them:
+
+- `system` (default): the System VM guest kernel (`configs/arcbox-{arch}.config`,
+  artifact `kernel-{arch}`). Full container stack: netfilter, cgroups
+  controllers, dm, overlayfs, NFS, HZ=1000/voluntary (ABX-498 tuning).
+- `microvm`: the Firecracker sandbox guest kernel
+  (`configs/arcbox-microvm-arm64.config`, artifact `microvm-kernel-arm64`,
+  arm64-only). Runs NESTED inside the System VM; optimized for kernel entry
+  → `/sbin/vm-agent` in the 200–300 ms class. virtio-mmio only — no
+  PCI/ACPI/EFI/netfilter/BPF; HZ=100/PREEMPT_NONE (nested ticks are
+  expensive). Consumed by boot-assets `upstream.toml` as the `vmlinux`
+  binary (`install_dir = "kernel"`).
+
+A flavor's load-bearing symbols are asserted post-`olddefconfig` in
+`scripts/build-kernel.sh` — extend the flavor's assertion list when adding a
+symbol whose silent loss would only surface at guest runtime.
+
 ## Build Commands
 
 ```bash
@@ -15,6 +32,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Build kernel for x86_64
 ARCH=x86_64 ./scripts/build-kernel.sh
 
+# Build the Firecracker sandbox microVM kernel (arm64-only)
+FLAVOR=microvm ./scripts/build-kernel.sh
+
 # Build kernel with specific version
 KERNEL_VERSION=6.18.0 ./scripts/build-kernel.sh
 
@@ -44,8 +64,9 @@ cargo build -p arcbox-agent --target aarch64-unknown-linux-musl --release
 ```
 arcbox-kernel/
 ├── configs/
-│   ├── arcbox-arm64.config     # ARM64 kernel config (Apple Silicon)
-│   └── arcbox-x86_64.config    # x86_64 kernel config
+│   ├── arcbox-arm64.config           # ARM64 System VM config (Apple Silicon)
+│   ├── arcbox-x86_64.config          # x86_64 System VM config
+│   └── arcbox-microvm-arm64.config   # ARM64 Firecracker sandbox config
 ├── scripts/
 │   ├── build-kernel.sh         # Kernel build (Docker-based)
 │   ├── build-initramfs.sh      # Initramfs build (Alpine + agent)

README.md

@@ -9,6 +9,25 @@ This repository contains:
 - Build scripts for kernel and initramfs
 - GitHub Actions CI for automated releases
 
+## Kernel Flavors
+
+Two independent guest kernels are built from the same kernel source:
+
+| Flavor | Config | Artifact | Boots |
+|--------|--------|----------|-------|
+| `system` (default) | `configs/arcbox-{arch}.config` | `kernel-{arch}` | ArcBox System VM (VZ/HV backends) |
+| `microvm` | `configs/arcbox-microvm-arm64.config` | `microvm-kernel-arm64` | Firecracker sandbox microVMs, nested inside the System VM |
+
+The microvm flavor is arm64-only for now: Firecracker x86_64 boots an ELF
+`vmlinux` (not a bzImage) and needs its own config
+(`VIRTIO_MMIO_CMDLINE_DEVICES`, kvmclock). It targets kernel entry →
+PID 1 in the 200–300 ms class under nested virtualization: virtio-mmio
+device model only, no PCI/ACPI/EFI/netfilter, everything built in.
+
+```bash
+FLAVOR=microvm ./scripts/build-kernel.sh
+```
+
 ## Features
 
 | Feature | Description |
@@ -49,8 +68,9 @@ tar -xzf arcbox-kernel-arm64-v0.1.0.tar.gz
 ```
 arcbox-kernel/
 ├── configs/
-│   ├── arcbox-arm64.config     # ARM64 kernel config
-│   └── arcbox-x86_64.config    # x86_64 kernel config
+│   ├── arcbox-arm64.config           # ARM64 System VM kernel config
+│   ├── arcbox-x86_64.config          # x86_64 System VM kernel config
+│   └── arcbox-microvm-arm64.config   # ARM64 Firecracker sandbox kernel config
 ├── scripts/
 │   ├── build-kernel.sh         # Kernel build script
 │   ├── build-initramfs.sh      # Initramfs build script