Runtime Selection

VoidBox selects the guest runtime from llm.provider.

claude, claude-personal, ollama, lm-studio, and custom execute claude-code.
codex executes the codex CLI directly.

LLM Provider Backends

Claude API (default)

The default path. VoidBox provisions your ANTHROPIC_API_KEY into the guest environment and claude-code calls the Claude API directly.

Claude Personal

claude-personal still runs claude-code, but stages your host OAuth credentials instead of requiring ANTHROPIC_API_KEY.

Claude-Compatible Local / Custom Endpoints

ollama, lm-studio, and custom keep the claude-code runtime and change only the endpoint and auth environment injected into the guest.

Codex

codex switches runtimes entirely. The guest executes the bundled codex binary and parses its JSON event stream directly.

Backend Selection

# From a clone of void-box
# Default provider path (Claude API)
cargo run --bin voidbox -- run --file examples/hackernews/hackernews_agent.yaml

# Same spec, Ollama backend through claude-code compatibility
VOIDBOX_LLM_PROVIDER=ollama \
VOIDBOX_LLM_MODEL=qwen3-coder \
cargo run --bin voidbox -- run --file examples/hackernews/hackernews_agent.yaml

# Switch the guest runtime to codex
VOIDBOX_LLM_PROVIDER=codex \
cargo run --bin voidbox -- run --file examples/hackernews/hackernews_agent.yaml

Skill Types

Skills are the composable units of capability injected into a VoidBox. Each type is provisioned differently in the guest environment:

Type	Constructor	Provisioned as	Example
Agent	`Skill::agent("claude-code")`	Reasoning engine designation	Claude-shaped runtime marker
File	`Skill::file("path/to/SKILL.md")`	`/workspace/.claude/skills/{name}.md`	Domain methodology
Remote	`Skill::remote("owner/repo/skill")`	Fetched from GitHub, then written to `/workspace/.claude/skills/`	`obra/superpowers/brainstorming`
MCP	`Skill::mcp("server-name")`	`/workspace/.mcp.json` for Claude-shaped runtimes, `~/.codex/config.toml` for Codex	Structured tool server
CLI	`Skill::cli("jq")`	Expected in guest initramfs	Binary tool

Guest Execution Model

Inside the micro-VM, the guest-agent runs as PID 1 and controls the full execution lifecycle:

Authentication — Validates the session secret received over vsock against the value injected via kernel cmdline at boot.
Policy enforcement — Reads /etc/voidbox/allowed_commands.json (command allowlist) and /etc/voidbox/resource_limits.json (rlimits). Applies setrlimit constraints for memory, file descriptors, and process count.
Privilege drop — Drops from root to uid:1000 before executing any user workload.
Fork + exec — Launches the runtime selected by llm.provider: claude-code for Claude-shaped providers, codex for Codex.

Skills are pre-provisioned before execution: file skills are written to /workspace/.claude/skills/, MCP discovery is written to /workspace/.mcp.json or ~/.codex/config.toml depending on runtime, and OCI skill images are mounted read-only at their declared paths.

Compatibility Guardrails

Runs fail fast when the guest image or runtime is incompatible with the required execution mode. This prevents silent failures where a spec expects capabilities not present in the guest. Use production guest image builds for runtime examples.