# 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

```bash
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

```bash
# 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