Runtime Model

Claude Code First-Class Runtime

VoidBox uses claude-code as the canonical agent runtime. This is the execution identity inside every guest environment -- regardless of which LLM provider backend is configured, the guest always runs claude-code.

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 over the SLIRP network.

Ollama (Claude-compatible mode)

When configured for Ollama, VoidBox still runs claude-code -- only the provider backend changes. The guest reaches Ollama on the host via the SLIRP gateway (10.0.2.2:11434). Claude-code's provider compatibility layer handles the translation.

Backend Selection

# Default provider path (Claude API)
cargo run --bin voidbox -- run --file examples/specs/hackernews_agent.json

# Same spec, Ollama backend through claude-code compatibility
VOIDBOX_LLM_PROVIDER=ollama \
VOIDBOX_LLM_MODEL=qwen2.5-coder:7b \
cargo run --bin voidbox -- run --file examples/specs/hackernews_agent.json

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	The LLM itself
File	`Skill::file("path/to/SKILL.md")`	`~/.claude/skills/{name}.md`	Domain methodology
Remote	`Skill::remote("owner/repo/skill")`	Fetched from GitHub, written to skills/	`obra/superpowers/brainstorming`
MCP	`Skill::mcp("server-name")`	Entry in `~/.claude/mcp.json`	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 claude-code with --output-format stream-json, streaming structured output back to the host over vsock.

Skills are pre-provisioned before execution: file skills are written to ~/.claude/skills/, MCP entries go to ~/.claude/mcp.json, 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.