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 resolves the kernel and initramfs in order: explicit spec paths → env vars → installed artifacts → provider-specific GitHub Releases artifacts → a pre-built guest image from GHCR. No manual build steps are required:

# Claude API path
ANTHROPIC_API_KEY=sk-ant-xxx \
cargo run --bin voidbox -- run --file examples/hackernews/hackernews_agent.yaml

# Ollama path
cargo run --bin voidbox -- run --file examples/specs/oci/agent.yaml

The default 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 7-step chain:

1. sandbox.kernel / sandbox.initramfs in the spec
2. VOID_BOX_KERNEL / VOID_BOX_INITRAMFS env vars
3. Installed artifacts (/usr/lib/voidbox/, package-manager paths, etc.)
4. Provider-specific artifacts auto-pulled from GitHub Releases (selected by llm.provider)
5. sandbox.guest_image in the spec
6. Default: ghcr.io/the-void-ia/voidbox-guest:v{version}
7. 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; Claude/Codex are only
# included if their binaries are available when the script runs)
scripts/build_guest_image.sh

# Download a kernel
scripts/download_kernel.sh

# Run a non-agent workflow with explicit paths
# (on arm64 hosts, use target/vmlinuz-arm64)
VOID_BOX_KERNEL=target/vmlinuz-amd64 \
VOID_BOX_INITRAMFS=/tmp/void-box-rootfs.cpio.gz \
cargo run --bin voidbox -- run --file examples/specs/oci/workflow.yaml

For provider-backed agent runs, build a provider-specific initramfs instead:

# Same image works for claude, claude-personal, ollama, lm-studio,
# and custom runtime providers
scripts/build_claude_rootfs.sh

# Codex
CODEX_VERSION=0.118.0 scripts/build_codex_rootfs.sh

Script intent summary

Script	Purpose
scripts/build_guest_image.sh	Base guest image for workflows, OCI rootfs work, and local experimentation
scripts/build_claude_rootfs.sh	Provider-ready image for claude, claude-personal, ollama, lm-studio, and custom
scripts/build_codex_rootfs.sh	Provider-ready image for codex
scripts/build_test_image.sh	Deterministic test image with claudio mock

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 \
OLLAMA_MODEL_STRATEGY=qwen3-coder \
VOID_BOX_KERNEL=/boot/vmlinuz-$(uname -r) \
VOID_BOX_INITRAMFS=target/void-box-rootfs.cpio.gz \
cargo run --example parallel_pipeline

Running tests

--test-threads=1 is required for KVM-backed tests — VM backends don’t share host state safely across concurrent runs.

Unit tests

cargo test --lib

Skill pipeline (mock)

cargo test --test skill_pipeline

OCI integration

cargo test --test oci_integration

VM conformance (KVM)

cargo test --test conformance -- --ignored --test-threads=1

End-to-end (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