Running on Linux

VoidBox runs natively on any Linux host with /dev/kvm. This guide covers zero-setup mode, manual image builds, mock mode for development, and running the test suite.

KVM Mode (Zero-Setup)

On a Linux host with /dev/kvm, VoidBox auto-pulls a pre-built guest image (kernel + initramfs) from GHCR on first run. No manual build steps required:

# Just works — guest image is pulled and cached automatically
ANTHROPIC_API_KEY=sk-ant-xxx \
cargo run --bin voidbox -- run --file examples/specs/oci/agent.yaml

# Or with Ollama
cargo run --bin voidbox -- run --file examples/specs/oci/workflow.yaml

The guest image (ghcr.io/the-void-ia/voidbox-guest) contains the kernel and initramfs with guest-agent, busybox, and common tools. It is cached at ~/.voidbox/oci/guest/ after the first pull.

Resolution Order

VoidBox resolves the kernel and initramfs using a 5-step chain:

1. sandbox.kernel / sandbox.initramfs in the spec (explicit paths)
2. VOID_BOX_KERNEL / VOID_BOX_INITRAMFS env vars
3. sandbox.guest_image in the spec (explicit OCI ref)
4. Default: ghcr.io/the-void-ia/voidbox-guest:v{version} (auto-pull)
5. Mock fallback when mode: auto

Custom Guest Image

To use a custom guest image or disable auto-pull:

sandbox:
  # Use a specific guest image
  guest_image: "ghcr.io/the-void-ia/voidbox-guest:latest"

  # Or disable auto-pull (empty string)
  # guest_image: ""

KVM Mode (Manual Build)

If you prefer to build the guest image locally:

# Build base guest initramfs (guest-agent + tools; no Claude bundle)
scripts/build_guest_image.sh

# Download a kernel
scripts/download_kernel.sh

# Run with explicit paths
ANTHROPIC_API_KEY=sk-ant-xxx \
VOID_BOX_KERNEL=target/vmlinuz-amd64 \
VOID_BOX_INITRAMFS=/tmp/void-box-rootfs.cpio.gz \
cargo run --example trading_pipeline

For a production Claude-capable initramfs:

# Build production rootfs/initramfs with native claude-code + CA certs + sandbox user
scripts/build_claude_rootfs.sh

Script Intent Summary

Mock Mode

No KVM required. Mock mode lets you develop and test pipeline logic without hardware virtualization:

cargo run --example quick_demo
cargo run --example trading_pipeline
cargo run --example parallel_pipeline

Parallel Pipeline

Run a parallel pipeline with per-box model overrides using environment variables:

OLLAMA_MODEL=phi4-mini \
OLLAMA_MODEL_QUANT=qwen3-coder \
OLLAMA_MODEL_SENTIMENT=phi4-mini \
VOID_BOX_KERNEL=/boot/vmlinuz-$(uname -r) \
VOID_BOX_INITRAMFS=target/void-box-rootfs.cpio.gz \
cargo run --example parallel_pipeline

Running Tests

Unit Tests

cargo test --lib

Integration Tests (Mock)

cargo test --test skill_pipeline

Integration Tests

cargo test --test integration

E2E Tests (KVM + test initramfs)

scripts/build_test_image.sh
VOID_BOX_KERNEL=/boot/vmlinuz-$(uname -r) \
VOID_BOX_INITRAMFS=/tmp/void-box-test-rootfs.cpio.gz \
cargo test --test e2e_skill_pipeline -- --ignored --test-threads=1