sparkvm is a minimal, secure, high-density microVM monitor for FreeBSD 16.0+. It is the FreeBSD-native equivalent of AWS Firecracker: a purpose-built VMM that creates and manages lightweight virtual machines optimized for fast boot, small footprint, and strong isolation.

🚧 Under Active Development - Currently implementing Task 0 (Project Scaffolding)

This is a hybrid Rust/C project that reuses bhyve's battle-tested device models via FFI and links against FreeBSD's system-provided libvmmapi.

• Fast boot: < 200ms to guest userspace
• Small footprint: < 5 MiB binary, < 5 MiB overhead per microVM
• Strong isolation: Capsicum capability mode + FreeBSD jails + RCTL limits
• Linux guests only: Modern Linux kernels (5.10+) with direct boot (no UEFI)
• High-performance I/O: NVMe emulation via bhyve's proven device models
• REST API: Firecracker-compatible HTTP-over-Unix-socket interface
• ZFS integration: O(1) copy-on-write disk provisioning

• Host OS: FreeBSD 16.0+ ONLY
• Guest OS: Modern Linux kernels (5.10+)
• Hardware: x86_64 with Intel VMX or AMD SVM
• Kernel module: vmm.ko loaded (kldload vmm)
• Source tree: FreeBSD source at /usr/src (for bhyve device models)

# Ensure FreeBSD source tree is installed
git clone -b main https://git.freebsd.org/src.git /usr/src

# Copy required bhyve device model sources
./tools/copy-bhyve-sources.sh

cargo build --release

The build produces two binaries:

• target/release/sparkvm-jailer - Privileged launcher (runs as root)
• target/release/sparkvm - VMM process (runs unprivileged in jail)

User/Orchestrator
       |
       | HTTP-over-Unix-Domain-Socket (REST API)
       v
+----------------------------------------------+
|                  sparkvm                      |
|         (unprivileged, jailed,                |
|          Capsicum capability mode)            |
|                                               |
|  Rust layer (~5,400 LOC)                      |
|  - REST API server                            |
|  - kqueue event loop                          |
|  - Linux direct boot loader                   |
|  - Capsicum sandbox                           |
|                                               |
|  FFI boundary                                 |
|  ─────────────────────────────────────────    |
|                                               |
|  bhyve C device models (~15,500 LOC reused)   |
|  - libvmmapi (system)                         |
|  - blockif (async block I/O)                  |
|  - pci_emul (PCI bus)                         |
|  - pci_nvme (NVMe controller)                 |
|  - virtio (VirtIO devices)                    |
|  - uart_emul (serial console)                 |
+------------------|----------------------------+
          ioctls via libvmmapi
===================|============================
                   v
+----------------------------------------------+
|         vmm.ko (FreeBSD kernel)               |
|         Intel VMX / AMD SVM                   |
+----------------------------------------------+

1. Reuse bhyve's device models - Don't reinvent the wheel. bhyve's NVMe, VirtIO, and PCI emulation are production-grade and optimized for FreeBSD.

2. System libvmmapi - Use FreeBSD's shipped libvmmapi for all vmm.ko interaction. No ioctl wrappers needed.

3. NVMe primary - Emulated NVMe outperforms virtio-blk on bhyve by up to 4x.

4. Linux direct boot - No UEFI, no BIOS. Parse bzImage, set up page tables, boot directly into long mode.

5. Security layers - Jail isolation + Capsicum capability mode + RCTL limits.

6. FreeBSD 16.0+ only - Leverage latest vmm.ko features: /dev/vmmctl, DESTROY_ON_CLOSE, allow.vmm jail parameter.

See AGENTS.md for the complete implementation plan.

• Task 0: Project scaffolding (IN PROGRESS)
• Task 1: libvmmapi FFI bindings
• Task 2: bhyve device model FFI bindings
• Task 3: vCPU management
• Task 4: Linux direct boot
• Task 5: Device initialization orchestration
• Task 6: kqueue event loop
• Task 7: REST API server
• Task 8: Capsicum sandboxing
• Task 9: Jailer
• Task 10: ZFS helpers
• Task 11: Main entry point

This project is in early development. See AGENTS.md for the detailed implementation plan and task breakdown.

• bhyve source - FreeBSD hypervisor
• libvmmapi - VM management API
• Linux boot protocol
• Firecracker - AWS microVM monitor
• Capsicum - FreeBSD capability mode

BSD-2-Clause. See LICENSE file.

Includes bhyve device model sources from FreeBSD, which are also BSD-licensed.