Brood Box CLI
The bbox CLI runs Claude Code, Codex and other agents inside a microVM and shows a diff before any change lands in your project
- 80 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- API keys and git tokens you list are forwarded into the virtual machine, and the agent may run arbitrary code there
- The no-snapshot mode turns diff review off and lets the agent write to the working folder directly
Install
- Works in
Manual install
task buildBuild from source: needs Go 1.26+ and Task; the binary lands in bin/.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- API keys and git tokens you list are forwarded into the virtual machine, and the agent may run arbitrary code there
- The no-snapshot mode turns diff review off and lets the agent write to the working folder directly
This is third-party code. Review the repository files before installing.
What it does
Brood Box is a `bbox` command-line program that runs coding agents in an isolated libkrun microVM with hardware virtualization: KVM on Linux and Hypervisor.framework on macOS. The `bbox claude-code` command makes a copy-on-write snapshot of the working folder, boots a machine from an image and opens an interactive terminal. When the agent exits, `bbox` shows a per-file diff and you accept or reject the changes. Claude Code, Codex, OpenCode, Hermes and Gemini CLI work out of the box, and custom agents go in the config. There is an egress firewall with three profiles, a proxy for ToolHive MCP servers and git token forwarding. The project is experimental, so config format and flags may change.
Who it is for. Developers who run agents with broad permissions and want them kept behind a virtual machine boundary, and teams with code isolation requirements.
Good fit when
- An agent runs without confirmations and you want to review every edit before it reaches the repository
- The working folder holds sensitive files that must not be exposed to the agent even by mistake
- You try an unfamiliar agent and limit its network with the `locked` profile
- One machine must run Claude Code and Codex in parallel on separate project copies
- The agent needs ToolHive MCP servers without access to your host system
Not a fit when
- You have no Linux with KVM or Apple Silicon Mac: without hardware virtualization the machine does not start
- You need a stable production base: the README itself warns about experimental status
- The agent should edit files in the project directly with no diff review
- You run the agent in a cloud where nested virtualization is unavailable
Example request
Run Claude Code in Brood Box on this project with 4 CPUs and show me a per-file diff on exitLimitations
The project is experimental: API, flags and config format change without notice. It needs Linux with an accessible `/dev/kvm` or macOS on Apple Silicon, your agent API key such as `ANTHROPIC_API_KEY` for Claude Code, and Go 1.26 or newer when building from source. The `libkrunfw` firmware is downloaded at start and cached in `~/.cache/broodbox/firmware/`. Through `env_forward` and the git token only the secrets you list enter the machine. The no-snapshot mode writes to the project directly and turns review off.
How to disable. Each session is ephemeral and leaves nothing after exit. To remove the program, delete the `bbox` binary from `/usr/local/bin/` and the `~/.cache/broodbox/` cache.
FAQ
How do I run Claude Code in Brood Box?
Export `ANTHROPIC_API_KEY` and run `bbox claude-code` in the project folder. When the session ends the program shows a per-file diff to accept or reject.
Why a microVM rather than a container?
A container shares the host kernel, while here the agent runs in a real virtual machine with KVM or Hypervisor.framework isolation.
Which agents are supported?
Claude Code, Codex, OpenCode, Hermes and Gemini CLI, via `bbox claude-code`, `bbox codex`, `bbox opencode`, `bbox hermes` and `bbox gemini`. Others go in the config or run through `bbox run-image`.
Which files stay hidden from the agent?
Files such as `.env`, `*.pem`, `.ssh/` and `.aws/` are always excluded from the snapshot, even if `.broodboxignore` tries to allow them.
How do I restrict the agent network?
Pick one of three egress firewall profiles: permissive, standard or locked. The filter is DNS-aware.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI that creates separate virtual machines for coding agents, keeping their development tools away from the main host system.
A single binary runs coding agents inside an isolated sandbox: a microVM, network policies and secrets hidden from the agent.
VibeKit runs Claude Code, Codex and other CLI agents through a proxy that masks secrets in replies, keeps a log and can hold the agent in Docker
A sandbox for commands and agent-written code: writes, network and environment variables are closed by default, keys are injected only for allowed domains
A local dashboard for Claude Code, Codex CLI and OpenCode: what the agent loads, its token cost and an MCP server security scan
Claude Code, Codex, OpenCode and pi run in a hardened container: project files only, allowlisted network, keys held by a proxy.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Brood Box (this card) | yes | 80 | ||
| Agent-Sandbox | no | key is optional | 232 | a sandbox for running code over MCP; Brood Box isolates the agent itself and reviews diffs |
| sandbox-mcp | no | 422 | container sandboxes for MCP tools; here hardware virtualization and a working folder snapshot |
README in short
The README explains kernel-level agent isolation, lists features, quick start steps, a table of supported agents with images and default resources, the flow and the security model. Details are moved to the docs folder.