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 first checks for installed artifacts (/usr/lib/voidbox/, Homebrew-style prefixes, etc.). If none are present, it falls back to a pre-built guest image (kernel + initramfs) 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 6-step chain:

sandbox.kernel / sandbox.initramfs in the spec
VOID_BOX_KERNEL / VOID_BOX_INITRAMFS env vars
Installed artifacts (/usr/lib/voidbox/, package-manager paths, etc.)
sandbox.guest_image in the spec
Default: ghcr.io/the-void-ia/voidbox-guest:v{version}
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
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:

# Claude / Ollama / LM Studio / custom Anthropic-compatible endpoints
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 \
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 oci_integration

VM Conformance (KVM)

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

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