volt-vmm/README.md

Neutron Stardust (Volt VMM)

A lightweight, KVM-based microVM monitor built for the Volt platform. Stardust provides ultra-fast virtual machine boot times, a minimal attack surface, and content-addressable storage for VM images and snapshots.

Architecture

Stardust is organized as a Cargo workspace with three members:

volt-vmm/
├── vmm/           — Core VMM: KVM orchestration, virtio devices, boot loader, API server
├── stellarium/    — Image management and content-addressable storage (CAS) for microVMs
└── rootfs/
    └── volt-init/ — Minimal init process for guest VMs (PID 1)

VMM Core (vmm/)

The VMM handles the full VM lifecycle:

• KVM Interface — VM creation, vCPU management, memory mapping (with 2MB huge page support)
• Boot Loader — PVH boot protocol, kernel/initrd loading, 64-bit long mode setup, MP tables for SMP
• VirtIO Devices — virtio-blk (file-backed and Stellarium CAS-backed) and virtio-net (TAP, vhost-net, macvtap) over MMIO transport
• Serial Console — 8250 UART emulation for guest console I/O
• Snapshot/Restore — Full VM snapshots with optional CAS-backed memory deduplication
• API Server — Unix socket HTTP API for runtime VM management
• Security — 5-layer hardening: seccomp-bpf, Landlock LSM, capability dropping, namespace isolation, memory bounds checking

Stellarium (stellarium/)

Content-addressable storage engine for VM images. Provides deduplication, instant cloning, and efficient snapshot storage using 2MB chunk-aligned hashing.

Volt Init (rootfs/volt-init/)

Minimal init process that runs as PID 1 inside guest VMs. Handles mount setup, networking configuration, and clean shutdown.

Build

cargo build --release

The VMM binary is built at target/release/volt-vmm.

Requirements

• Linux x86_64 with KVM support (/dev/kvm)
• Rust 1.75+ (2021 edition)
• Optional: 2MB huge pages for reduced TLB pressure

Usage

# Boot a VM with a kernel and root filesystem
./target/release/volt-vmm \
    --kernel /path/to/vmlinux \
    --rootfs /path/to/rootfs.ext4 \
    --memory 128M \
    --cpus 2

# Boot with Stellarium CAS-backed storage
./target/release/volt-vmm \
    --kernel /path/to/vmlinux \
    --volume /path/to/volume-dir \
    --cas-store /path/to/cas \
    --memory 256M

# Boot with networking (TAP + systemd-networkd bridge)
./target/release/volt-vmm \
    --kernel /path/to/vmlinux \
    --rootfs /path/to/rootfs.ext4 \
    --net-backend virtio-net \
    --net-bridge volt0

Key Features

• Sub-125ms boot — PVH direct boot, demand-paged memory, minimal device emulation
• 5-layer security — seccomp-bpf syscall filtering, Landlock filesystem sandboxing, capability dropping, namespace isolation, guest memory bounds validation
• Stellarium CAS — Content-addressable storage with 2MB chunk deduplication for images and snapshots
• VirtIO block & net — virtio-blk with file and CAS backends; virtio-net with TAP, vhost-net, and macvtap backends
• Snapshot/restore — Full VM state snapshots with CAS-backed memory deduplication and pre-warmed VM pool for fast restore
• Huge page support — 2MB huge pages for reduced TLB pressure and faster memory access
• SMP support — Multi-vCPU VMs with MP table generation

License

Apache-2.0