Guide

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.

One-Time Setup

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

Terminal

# Install the musl cross-compilation toolchain
brew install filosottile/musl-cross/musl-cross

Add the Rust target for Linux ARM64:

Terminal

rustup target add aarch64-unknown-linux-musl

Build and Run

Download the kernel, build the guest initramfs, compile, codesign, and run:

Terminal

# Download an ARM64 Linux kernel (cached in target/)
scripts/download_kernel.sh

# Build the guest initramfs (cross-compiles guest-agent, downloads claude-code + busybox)
scripts/build_claude_rootfs.sh

# Build the example and sign it with the virtualization entitlement
cargo build --example ollama_local
codesign --force --sign - --entitlements voidbox.entitlements target/debug/examples/ollama_local

# Run (Ollama must be listening on 0.0.0.0:11434)
OLLAMA_MODEL=qwen3-coder \
VOID_BOX_KERNEL=target/vmlinux-arm64 \
VOID_BOX_INITRAMFS=target/void-box-rootfs.cpio.gz \
target/debug/examples/ollama_local

Important: Code Signing

Every cargo build invalidates the code signature. You must re-run codesign after each rebuild, or macOS will refuse to grant the virtualization entitlement and the VM will fail to start.

CLI Shortcut

When using the voidbox CLI, cargo run automatically codesigns before executing (via .cargo/config.toml runner). Just run:

Terminal

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

Direct Binary

If running the binary directly (e.g. ./target/debug/voidbox), you must codesign manually first:

Terminal

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

Then run with the required environment variables:

Terminal

VOID_BOX_KERNEL=target/vmlinux-arm64 \
VOID_BOX_INITRAMFS=target/void-box-rootfs.cpio.gz \
./target/debug/voidbox run --file examples/specs/oci/agent.yaml