void-box logoVoid-Box
Guide

Getting Started

This guide walks you through installing VoidBox, defining your first agent, and running it. By the end you will have an isolated micro-VM executing a prompt-driven workflow.

Prerequisites

  • Linux — Any host with /dev/kvm available (most cloud instances and bare-metal servers).
  • macOS — Apple Silicon Mac (M1 or later). Uses Virtualization.framework natively.
  • Rust 1.83+ — Install via rustup if you do not have it.

Install

Add VoidBox as a library dependency:

Terminal
cargo add void-box

Or install the CLI binary:

Terminal
cargo install void-box

First Agent (Rust API)

Declare skills, bind them to an isolated execution boundary, and run:

use void_box::agent_box::VoidBox;
use void_box::skill::Skill;
use void_box::llm::LlmProvider;

// Skills = declared capabilities
let hn_api = Skill::file("skills/hackernews-api.md")
    .description("HN API via curl + jq");

let reasoning = Skill::agent("claude-code")
    .description("Autonomous reasoning and code execution");

// VoidBox = Agent(Skills) + Isolation
let researcher = VoidBox::new("hn_researcher")
    .skill(hn_api)
    .skill(reasoning)
    .llm(LlmProvider::ollama("qwen3-coder"))
    .memory_mb(1024)
    .network(true)
    .prompt("Analyze top HN stories for AI engineering trends")
    .build()?;

First Agent (YAML)

The same agent defined declaratively:

# hackernews_agent.yaml
api_version: v1
kind: agent
name: hn_researcher

sandbox:
  mode: auto
  memory_mb: 1024
  network: true

llm:
  provider: ollama
  model: qwen3-coder

agent:
  prompt: "Analyze top HN stories for AI engineering trends"
  skills:
    - "file:skills/hackernews-api.md"
    - "agent:claude-code"
  timeout_secs: 600

Run It

With the Rust API:

Terminal
cargo run

With the CLI and a YAML spec:

Terminal
voidbox run --file hackernews_agent.yaml

What Happens

When you run a VoidBox agent, the following sequence executes automatically:

  1. OCI image auto-pull — The guest image (kernel + initramfs) is pulled from GHCR and cached locally. No manual build steps required.
  2. VM boot — A micro-VM boots with hardware isolation (KVM on Linux, Virtualization.framework on macOS).
  3. Guest-agent init — The guest-agent (PID 1) authenticates over vsock, applies security policies, and drops privileges.
  4. claude-code execution — The Claude Code runtime executes your prompt with the declared skills, calling the configured LLM backend.
  5. Result return — Structured output (tokens, cost, tool calls, result text) is returned over vsock to the host.

Next Steps