Void-Box logo Void-Box

Getting Started

Define a minimal agent spec, run it inside a micro-VM, and see the result — end to end in under a minute.

Prerequisites

  • Host — Linux with /dev/kvm available, or an Apple Silicon Mac (M1 or later) for Virtualization.framework.
  • CLI — voidbox on your PATH (see Installation).
  • Provider credential — an agent needs a provider, so the examples pick Claude and expect ANTHROPIC_API_KEY. See Alternative providers to swap in Codex, Ollama, LM Studio, or any Anthropic-compatible endpoint.

1. Set your API key

export ANTHROPIC_API_KEY=sk-ant-...

2. Write a minimal spec

Save this as hello.yaml:

api_version: v1
kind: agent
name: hello

sandbox:
  memory_mb: 2048
  vcpus: 4
  network: true

llm:
  provider: claude

agent:
  prompt: >
    Write a short haiku about hardware isolation and save it
    to /workspace/output.md.

That’s a complete agent: the runtime picked by llm.provider, a sandbox sized for the run, and a prompt. No skills declared — the built-in file tools of the runtime are enough for this task.

3. Run it

voidbox run --file hello.yaml

On the first run, VoidBox auto-pulls the guest image (kernel + initramfs) from GHCR. This is a one-time download of roughly 200 MB; subsequent runs start from cache.

What happens

  1. OCI image auto-pull — The guest image (kernel + initramfs) is pulled from GHCR and cached locally.
  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 policy (allowlist, rlimits, network deny list), and drops privileges to uid:1000.
  4. Runtime execution — The guest launches the runtime selected by llm.provider — claude-code for Claude-shaped providers, codex for Codex — with the declared skills provisioned.
  5. Result return — Structured output (tokens, cost, tool calls, result text) is returned over vsock to the host.

Try a richer example

The bundled HackerNews agent shows skills in action: a file skill supplies API methodology, and the agent drafts a themed briefing.

git clone https://github.com/the-void-ia/void-box.git
cd void-box
voidbox run --file examples/hackernews/hackernews_agent.yaml

The spec:

# examples/hackernews/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 top stories, group them by theme,
    and write a markdown briefing to /workspace/output.md.
  skills:
    - 'file:examples/hackernews/skills/hackernews-api.md'
  timeout_secs: 600

One file skill (a methodology markdown), Claude as the reasoning engine, and a micro-VM sandbox sized for the run. The file-skill reference is a path relative to the repo, which is why this example is run from a checkout. Browse examples/ for more, and YAML Specs for every field.

Alternative providers

The llm.provider field picks the agent binary and auth:

ProviderAuthNotes
claudeANTHROPIC_API_KEY in host envDefault path used above.
claude-personalHost ~/.claude OAuth credentialsNo API key needed.
codexHost ~/.codex/auth.json (ChatGPT login) or OPENAI_API_KEYUses the codex binary instead of claude-code.
ollamaLocal Ollama on the hostReached via the guest-to-host networking gateway.
lm-studioLocal LM Studio on the hostReached via the guest-to-host networking gateway.
customCustom ANTHROPIC_BASE_URLAny Anthropic-compatible endpoint.

Swap llm.provider in the spec and set the matching auth. See Runtime Model for the full provider-to-runtime mapping and Local LLMs with Ollama for the Ollama path in detail.

Alternative entry points

Rust library

Add the crate and build a VoidBox in code:

cargo add void-box
use void_box::agent_box::VoidBox;
use void_box::skill::Skill;
use void_box::llm::LlmProvider;

let researcher = VoidBox::new("hn_researcher")
    .skill(Skill::file("examples/hackernews/skills/hackernews-api.md"))
    .skill(Skill::agent("claude-code"))
    .llm(LlmProvider::Claude)
    .memory_mb(2048)
    .network(true)
    .prompt("Analyze top HN stories for AI engineering trends.")
    .build()?;

let result = researcher.run(None, None).await?;

From a clone without installing

If you have a void-box checkout and Rust 1.88+ but no installed binary, you can invoke the CLI through cargo run:

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

Next steps