void-box CLI
Runs each agent stage in its own micro-VM: Claude, Codex, Ollama or any CLI, with OTLP tracing
- 89 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Agents run with provider keys and may receive repository tokens. Isolation limits damage, but the user decides which secrets to hand out.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/the-void-ia/void-box/main/scripts/install.sh | shThe first README command installs the `voidbox` CLI, so read the script first. Then `voidbox run --file <spec>`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Agents run with provider keys and may receive repository tokens. Isolation limits damage, but the user decides which secrets to hand out.
This is third-party code. Review the repository files before installing.
What it does
void-box isolates each stage of an agent run in its own micro-VM: through KVM on Linux and Virtualization.framework on macOS. Inside you can run Claude Code, Codex, Ollama, LM Studio, OpenRouter or any program from `PATH`. Stages are combined into pipelines and described in YAML specs, with parallel branching through `.fan_out()` and merging through `.pipe()`. The README describes fast restore from a snapshot (about 138 ms warm and 252 ms cold), OCI images from GHCR, running without root through SLIRP usermode networking and OTLP traces for every stage. Tokens such as `GITHUB_TOKEN` are handed only to the stage that needs them. A run starts with `voidbox run --file <spec>`.
Who it is for. Engineers who run agents with access to repositories and secrets and want a hardware boundary to limit the damage from a prompt injection.
Good fit when
- A two-stage review pipeline where an analyzer reads untrusted code and only the second stage gets the PR token
- Parallel research branches with different skill sets merge into one report
- A local model runs through Ollama or LM Studio with no keys and no cloud round-trip
- You want traces and metrics for every agent step in the OpenTelemetry standard
Not a fit when
- A plain Docker container is enough, since micro-VMs need KVM or Virtualization.framework
- You want a simple agent MCP server with no isolation and no pipelines
- A machine without virtualization, such as some cloud VMs with no nested KVM
Example request
Run the research pipeline from examples/hackernews/hackernews_agent.yaml and show the trace by stageLimitations
KVM support on Linux or Virtualization.framework on macOS is required. The README installer runs through `curl ... | sh`, so read the script before running it. Host credentials such as OAuth tokens are mounted into the guest read-only, and API keys are passed as session environment variables. A Rust build needs version 1.88 or later. Some examples, including the trading pipeline, are demonstrations and need your own provider keys.
How to disable. Remove the `voidbox` binary (`brew uninstall voidbox` if installed through Homebrew) and the image and snapshot directories it created.
FAQ
How do I install void-box?
Run `curl -fsSL https://raw.githubusercontent.com/the-void-ia/void-box/main/scripts/install.sh | sh`. There are also `brew install the-void-ia/tap/voidbox` and `cargo install void-box`.
Is root required?
No. Networking runs in usermode through SLIRP on `smoltcp`, with no TAP devices and no elevated privileges.
Which models and agents can run?
Claude Code, OpenAI Codex, Ollama, LM Studio, OpenRouter, Together AI and any Anthropic-compatible endpoint. The provider is chosen with one configuration field.
How does it differ from smolvm?
void-box builds multi-stage agent pipelines with OTLP traces and snapshots, while smolvm covers running a single isolated machine.
How do I check the install worked?
Run the README example `voidbox run --file examples/hackernews/hackernews_agent.yaml`. First run and provider setup are covered in the Getting Started section of the documentation site.
Discussion
No questions or reviews yet.
Related
CLI toolsArcBox runs Claude Code in a disposable microVM on a Mac: its own kernel, an empty workspace and a start in about a second
AgentBox runs Claude Code, Codex and Open Code in separate virtual machines on your PC, a self-hosted server or a cloud.
ExitBox runs Claude, Codex, Cursor and other agents in rootless containers: a domain allowlist and secrets in an encrypted vault.
ClaudeBox runs Claude Code in Docker with language profiles, session slots and a firewall with an allowlist of addresses.
A Docker sandbox for coding agents: a Debian image with Copilot CLI, Codex and Pi, and SSH, RDP and Docker enabled by flags.
A CLI that gives every feature its own Git worktree and environment so agents and people work in parallel without colliding
README in short
The README promises hardware isolation for each agent stage, shows scenarios such as a research pipeline, PR review, an OpenClaw Telegram gateway and local models, then contrasts the approach with containers and covers protections and install options.