vz#

Apple Virtualization.framework bindings for OCaml.

OCaml bindings for Apple's Virtualization.framework on macOS 13+. Supports direct kernel boot via VZLinuxBootLoader, virtio-net and virtio-blk devices, serial ports (pty or file-handle backed), memory balloon, and Rosetta x86-64 translation. The bindings use C stubs to call the Objective-C framework directly, with no external dependencies beyond macOS.

VM configuration uses an immutable builder pattern: start with a name, add CPUs, memory, kernel, initrd, devices, then validate and boot. The Vm module handles the full lifecycle: create, start, pause, resume, stop, and graceful shutdown via the guest agent.

Installation#

opam install vz

Usage#

let config =
  Vz.Config.v ~name:"my-vm"
  |> Vz.Config.with_cpus 2
  |> Vz.Config.with_memory_mb 1024
  |> Vz.Config.with_kernel "/path/to/vmlinuz"
  |> Vz.Config.with_initrd "/path/to/initramfs"
  |> Vz.Config.with_cmdline "console=hvc0"
  |> Vz.Config.with_disk "/path/to/disk.img"
  |> Vz.Config.with_network Vz.Config.Nat
in
match Vz.Vm.v config with
| Ok vm ->
    ignore (Vz.Vm.start vm);
    (* vm is now running *)
    ignore (Vz.Vm.request_stop vm)
| Error e -> failwith e

API#

• Vz.Config -- Immutable VM configuration builder. Set CPU count (1--32), memory (128--65536 MB), kernel and initrd paths, command line, disks (virtio-blk), network devices (NAT or file-handle), serial ports (pty or file-handle), memory balloon, and Rosetta translation. Call validate before creating a VM.
• Vz.Vm -- VM lifecycle management. Create a VM from a validated config, then start, pause, resume, stop, or request graceful shutdown. Query the current state (Stopped, Running, Paused, Error, Starting, Pausing, Resuming, Stopping). The supported function checks for macOS 13+ with Virtualization.framework.

References#

• Apple Virtualization.framework documentation
• VZLinuxBootLoader