smartvm/assets/base-images/readme.md

SmartVM Base Image Bundles

This directory documents the project-owned base image manifest format. The actual kernel and rootfs binaries should be hosted as release assets or in object storage, not committed to git.

Bundle Layout

A hosted bundle should expose three files:

smartvm-minimal-v1-x86_64.manifest.json
vmlinux
rootfs.ext4

The manifest is the only file shape smartvm needs to know. It points at the hosted kernel and rootfs artifacts and records checksums.

Manifest Fields

• schemaVersion: currently 1
• bundleId: stable cache key, using letters, numbers, dot, underscore, and dash only
• arch: x86_64 or aarch64
• firecrackerVersion: Firecracker version validated with this bundle
• rootfsType: ext4 or squashfs
• rootfsIsReadOnly: use true for squashfs or immutable rootfs images
• bootArgs: kernel boot args to use with the bundle
• kernel: hosted kernel artifact URL/path plus sha256 for URL artifacts and optional sizeBytes
• rootfs: hosted rootfs artifact URL/path plus sha256 for URL artifacts and optional sizeBytes
• fileName: optional plain output filename; path separators are rejected

sha256 is required for hosted URL artifacts. sizeBytes is optional but helps catch incomplete downloads.

Cache Behavior

Downloaded bundles are cached under /tmp/.smartvm/base-images by default. The cache keeps two bundles unless maxStoredBaseImages is configured. Eviction is announced with console.warn.