Void-Box logo Void-Box

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.88+ — Install via rustup if you do not have it.

Install

Add VoidBox as a library dependency:

cargo add void-box

Or install the CLI binary:

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 repository includes a declarative example spec at examples/hackernews/hackernews_agent.yaml:

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

sandbox:
  mode: auto
  memory_mb: 2048
  vcpus: 4
  network: true

llm:
  provider: claude

agent:
  prompt: >
    Use the HackerNews API skill to fetch real data via curl and jq.
    Fetch the top stories, group them by theme, and write a markdown report.
  skills:
    - "file:examples/hackernews/skills/hackernews-api.md"
  timeout_secs: 600

Run It

From a repository clone, run the example spec through the local CLI:

cargo run --bin voidbox -- run --file examples/hackernews/hackernews_agent.yaml

With an installed voidbox binary:

voidbox run --file examples/hackernews/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. Runtime execution — The guest launches the runtime selected by llm.provider: claude-code for Claude-shaped providers, codex for Codex.
  5. Result return — Structured output (tokens, cost, tool calls, result text) is returned over vsock to the host.

Next Steps