Virtualization Backends

Virtualization Backends

heyvm runs each sandbox through a pluggable backend driver. The same CLI and API work across all of them — Firecracker micro-VMs, full KVM/QEMU VMs, Docker containers, Apple Virtualization, namespace sandboxes, and WebAssembly runtimes.

The abstraction

The driver layer lives in mvm-ctrl/src/driver/. Two core async traits define every backend:

  • VmBackend — the factory for a backend: create_sandbox, create_sandbox_with_net, restart_sandbox, restore_from_sync, and so on.
  • VmHandle — the lifecycle of a single sandbox: start, stop, destroy, execute, execute_streaming, run_interactive_shell, checkpoint, fork_to, package_for_sync, export_rootfs_tar, get_metrics, and more.

A BackendRegistry registers every backend that is valid for the current platform. The canonical list of backends is the BackendType enum.

Choosing a backend

There are three ways a backend gets selected, in order of precedence:

  1. Per-sandbox override — pass --backend <name> (alias --backend-type) on the CLI, or set backend_type in an API create request:

    heyvm create --name demo --backend firecracker --image default

  2. Saved default — the backend_type field in ~/.heyo/settings.json, written by the installer's setup flow or from the TUI's defaults screen.

  3. Platform default — when neither of the above is set:

    Platform Default backend
    macOS apple_container
    Linux bubblewrap
    Windows hyperv
    other msb

    Worktree sandboxes on Linux prefer Docker, then Firecracker (if /dev/kvm is present), then bubblewrap.

Restricting available backends

Set the MVM_BACKENDS environment variable to a comma-separated allow-list to register only those backends. Everything else is skipped for reconciliation, creation, and listing:

export MVM_BACKENDS=firecracker,libvirt

Valid names: msb, hyperv, windows_sandbox, wasix, wasip2, docker, apple_container, apple_vf, apple_virt, bubblewrap, sandbox_exec, libvirt, firecracker, firecracker_containerd, kvm.

Virtual networking

Backends share a backend-neutral virtual networking layer configured through environment variables:

  • HEYO_VIRT_NETWORK (plus _MODE, _ADDRESS, _NETMASK, _DHCP_START, _DHCP_END).
  • Backend-specific aliases: HEYO_LIBVIRT_SDN_*, HEYO_APPLE_VIRT_NETWORK_*, HEYO_HYPERV_NETWORK_*, HEYO_FIRECRACKER_NETWORK_*.

The backends

Backends are grouped by platform in the following pages:

  • Linux Backends — Firecracker, firecracker-containerd, libvirt/KVM, direct KVM (kvm), Docker, bubblewrap.
  • macOS Backends — Apple Virtualization, Apple Containers, sandbox-exec.
  • Windows Backends — Hyper-V, Windows Sandbox.
  • WebAssembly Backends — WASIX, WASI Preview 2.
  • Microsandbox (msb) — the cross-platform micro-VM path backed by the microsandbox server; requires msb server start and MSB_API_KEY.