Running on macOS

VoidBox runs natively on Apple Silicon Macs using Apple’s Virtualization.framework. No Docker or Linux VM required.

Overview

VoidBox on macOS uses Virtualization.framework (VZ) directly on Apple Silicon (M1 or later). This gives you the same hardware-isolated micro-VM execution model as Linux/KVM, with no container runtime dependency.

Minimum macOS version: 13 (Ventura) for basic VZ, 14 (Sonoma) to use snapshot/restore.

One-time setup

Install the musl cross-compilation toolchain. This compiles from source and takes approximately 30 minutes the first time:

brew install filosottile/musl-cross/musl-cross

Add the Rust target for Linux ARM64:

rustup target add aarch64-unknown-linux-musl

Build the guest artifacts

Download the kernel:

# ARM64 Linux kernel (uncompressed, required by VZ) — cached in target/
scripts/download_kernel.sh

Pick a rootfs build script based on which agent binaries you want bundled into the initramfs. All three scripts detect Apple Silicon hosts and auto-download the required Linux agent binaries — no separate Linux build needed.

Script	Output	Bundles
scripts/build_claude_rootfs.sh	target/void-box-claude.cpio.gz	claude-code only
scripts/build_codex_rootfs.sh	target/void-box-codex.cpio.gz	codex only
scripts/build_agents_rootfs.sh	target/void-box-agents.cpio.gz	claude-code and codex

scripts/build_claude_rootfs.sh

Run

macOS refuses to grant the virtualization entitlement unless the binary carries a valid code signature. Every cargo build invalidates the signature, so something has to re-sign after each rebuild. The two run paths below handle this differently.

With cargo run (recommended)

cargo run auto-codesigns before executing via the .cargo/config.toml runner — no manual codesign step needed. This works for both the voidbox binary and cargo run --example.

cargo run --bin voidbox -- run --file examples/specs/oci/guest-image-workflow.yaml

With a pre-built binary

If running the binary directly, you must codesign it manually first (and repeat after every rebuild):

codesign --force --sign - --entitlements voidbox.entitlements target/debug/voidbox

VOID_BOX_KERNEL=target/vmlinux-arm64 \
VOID_BOX_INITRAMFS=target/void-box-claude.cpio.gz \
./target/debug/voidbox run --file examples/specs/oci/guest-image-workflow.yaml

Example: ollama_local

End-to-end run against a host-local Ollama. Ollama must bind to 0.0.0.0 — the guest reaches the host via the VZ NAT gateway at 192.168.64.1, which a 127.0.0.1-only listener won’t accept.

# On the host, make Ollama reachable from the guest
OLLAMA_HOST=0.0.0.0:11434 ollama serve

# Build + codesign + run the example
cargo build --example ollama_local
codesign --force --sign - --entitlements voidbox.entitlements target/debug/examples/ollama_local

OLLAMA_MODEL=qwen3-coder \
VOID_BOX_KERNEL=target/vmlinux-arm64 \
VOID_BOX_INITRAMFS=target/void-box-claude.cpio.gz \
target/debug/examples/ollama_local

Or skip the separate cargo build + codesign steps with the runner:

OLLAMA_MODEL=qwen3-coder \
VOID_BOX_KERNEL=target/vmlinux-arm64 \
VOID_BOX_INITRAMFS=target/void-box-claude.cpio.gz \
cargo run --example ollama_local