vmz

vmz is a smol¹ Zig CLI to boot Alpine Linux on macOS using Virtualization.framework, try it today, break it, report bugs!

Warning

only runs on apple silicon macOS with Virtualization.framework support.

curl -LO https://f.rcast.dev/vmz
chmod +x ./vmz    # rw- > rwx
./vmz download -y # download alpine's latest stable initrd and kernel
./vmz             # run the VM
./vmz nuke        # cleanup downloaded files
rm ./vmz          # goodbye, take care polar bear!

vmz currently:

• downloads Alpine Linux netboot kernel and initramfs
• boots the VM configuring:
  • kernel path
  • initrd path
  • kernel cmdline
  • memory size
  • cpu count
  • networking (NAT)
  • escape key

vmz boots Alpine Linux VMs on macOS using Virtualization.framework.

usage:
  vmz [version]
  vmz run [options]
  vmz download [-y|--yes] [version]
  vmz nuke [-y|--yes]
  vmz version

commands:
  vmz [version]
      boot a downloaded Alpine version, defaults to `latest-stable`.

  vmz download [-y|--yes] [version]
      download alpine netboot files and unpack the kernel.
      prompts for confirmation, use -y to skip.

  vmz run [options]
      boot directly from local kernel and initrd files
      useful for experimentation

  vmz nuke
      delete all downloaded vmz assets.
      prompts for confirmation, use -y to skip.

downloaded assets are stored in: `~/Library/Application Support/vmz/<version>/`

development

the Zig entry point calls a tiny Swift bridge (lib/libvmz.swift) through the C ABI declared in lib/libvmz.h.

requirements

• Apple Command Line Tools, including codesign
• zig 0.16.0 (download), or use the provided nix development shell with nix develop

build:

zig build # adds virtualization entitlement via `codesign`

build, sign and launch:

zig build run -- download -y
zig build run -- run

---

1. binary size (main): 641KB ↩︎