Brood Box
Run coding agents in hardware-isolated microVMs and review workspace changes before they are applied.
- Source repo
- stacklok/brood-box
- Stars
- ★ 81
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Go
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers who want Claude Code to work on a project copy inside a real VM and want to inspect changes before applying them.
- Not a fit if
- Teams that need a stable production tool with fixed behavior
- Users running Linux machines without accessible KVM
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-20latest release v0.0.25 (2026-09-14)
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Brood Box is a Go CLI that starts microVMs through libkrun, using KVM on Linux or Hypervisor.framework on Apple Silicon macOS. It mounts a copy-on-write snapshot of the current workspace and can run Claude Code, Codex, OpenCode, Hermes, Gemini CLI, or configured custom agents. Agents run in the guest through an interactive terminal; after exit, Brood Box computes file changes, offers per-file review, and flushes accepted changes back to the workspace. It also provides DNS-aware egress profiles, credential forwarding, and a proxy for ToolHive MCP servers. The project is marked experimental, and its CLI flags, configuration, and behavior may change.
When invoked with commands such as bbox claude-code or bbox codex, the tool creates a copy-on-write workspace snapshot, pulls an OCI image, extracts its root filesystem, injects the init binary and SSH keys, and boots a microVM. The guest runs bbox-init as PID 1, configures networking and the workspace mount, and provides an embedded SSH server; the user runs the agent in an interactive SSH terminal. On exit, the VM stops and Brood Box uses SHA-256 based diffing to show changes, supports per-file review, and flushes accepted changes to the workspace. Users can configure egress profiles, allowed hosts, environment forwarding, the MCP proxy, and Git credential forwarding.
- Developers who want Claude Code to work on a project copy inside a real VM and want to inspect changes before applying them.
- Engineering teams using Codex, OpenCode, Hermes, or Gemini CLI that want to run them through the same
bboxCLI workflow. - Security engineers who need to set agent egress access to permissive, standard, or locked profiles.
- Developers who need Git access inside the VM and want to choose whether to forward a token or SSH agent.
- Teams using ToolHive MCP servers that want Brood Box to discover and proxy them into the VM.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Environment variables
ANTHROPIC_API_KEY- Runtime
- Go 1.26+
- Install notes cover
- macOS · Linux
How do you install or deploy this agent?
The documented host requirements are Linux with accessible /dev/kvm, or Apple Silicon macOS with Hypervisor.framework, plus Go 1.26+, Task, and curl. You can download a prebuilt binary from GitHub Releases; the README also documents a source build. Running an agent requires its corresponding API key, such as ANTHROPIC_API_KEY for Claude Code. Example:
# Linux amd64 example: after downloading and extracting the matching GitHub Release archive
sudo mv bbox /usr/local/bin/Build from source with:
task buildHow do you use this agent?
Set the API key for your chosen agent, then run its command from the project directory. By default, Brood Box creates a workspace snapshot; on exit, you can review each file's diff and accept or reject changes.
export ANTHROPIC_API_KEY="sk-ant-..."
bbox claude-codeUse --review for interactive per-file review or --egress-profile locked to restrict outbound access. In snapshot mode, only accepted changes are flushed back to the workspace.
What are this agent's strengths and limitations?
- Uses libkrun to run hardware-isolated VMs through KVM or Hypervisor.framework instead of containers sharing the host kernel.
- Runs against a copy-on-write workspace snapshot by default, with per-file diff review and accepted changes flushed back.
- Supports Claude Code, Codex, OpenCode, Hermes, Gemini CLI, and configured custom agents.
- Offers three DNS-aware egress profiles, additional host allowlisting, and a ToolHive MCP proxy.
- The project is experimental; CLI flags, configuration format, and behavior may change between releases.
- Requires Linux KVM or Apple Silicon macOS Hypervisor.framework; support for other host environments is not documented.
- Running an agent requires its API key, and installation or builds require the documented host tools.
- Direct workspace mode writes immediately and skips snapshot review and Git credential sanitization.
How does this agent compare with similar options?
The README contrasts Brood Box with containers that share the host kernel: Brood Box uses hardware-isolated microVMs. It also says direct workspace mode lets the agent write to the workspace immediately, while the default snapshot mode provides diff review.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Brood Box This agent | 53 · Major gaps | CLIFree + model costs | ★ 81 | today | Go | Codex · Claude Code |
| Alas Agent Workspace | 79 · Good | Desktop appFree + model costs | ★ 25 | today | Swift | Codex · Claude Code |
| Agent Teams AI | 63 · Some gaps | Desktop appFree + model costs | ★ 2.5k | today | TypeScript | Codex · Claude Code |
| Argot Repository Style Analyzer | 78 · Good | CLIFree | ★ 48 | 2mo ago | Rust | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
README and source show layered isolation: KVM microVM, COW snapshot, snapshot-by-default, --review per-file approval, --yes gate on first direct-mode use, non-negatable sensitive-file patterns, hash re-verification and setuid stripping on flush, localhost-only SSH, per-session ephemeral keys. These are concrete least-privilege and confirmation designs, so least_privilege/user_confirmation/rollback score 2. However the dependency surface is very broad (toolhive, docker, aws-sdk, ory and many indirect deps) with no visible dependency audit or SBOM, so dependency_security is 1. Data flow is described at a high level (secret forwarding, MCP proxy) but not itemized per destination, so data_flow_transparency and sensitive_data_handling are 2, not 3.
CLAUDE.md and README disagree on supported agents (CLAUDE.md lists only claude-code/codex/opencode; README and CLI help list hermes/gemini), and README says Go 1.26+ while go.mod requires 1.27.0 — self_consistency 1. Runtime depends on downloading libkrunfw firmware and prebuilt go-microvm runtime artifacts, an external single point, so dependency_availability 1. Source shows slog error logging and explicit halt paths with specific messages, so failure_messages 2.
README clearly targets developers running coding agents locally (audience_and_scenarios 2); capability boundaries are documented (snapshot vs direct, three egress profiles, MCP toggle) (capability_boundaries 2). Trigger precision is weak: many CLI flags, complex three-level config merge, and some per-workspace fields silently ignored, making behavior hard to predict (trigger_precision 1). Environment fit is limited to Linux KVM and Apple Silicon macOS with no Windows/Intel Mac guidance (environment_fit 1).
README has a TOC, install, config, security model and docs index — good information architecture (2); install notes cover release binaries and source build (2); examples are plentiful (2); EXPERIMENTAL status and API instability are stated (known_limitations 2); LICENSE is full Apache-2.0 with SPDX headers in source (license 3). Naming stability is weak: project self-declares EXPERIMENTAL with behavior changes without notice (naming_stability 1); no CHANGELOG or versioning policy (versioning_changelog 1); maintenance responsibility rests only on a copyright line, and publisher identity is unverified (maintenance_responsibility 1).
Output usability is good: snapshot diff review, per-file accept/reject, unified diffs — directly usable artifacts (output_usability 2). Marginal value over running agents bare is clear: hardware isolation plus change review (marginal_value 2). But cost is high: requires KVM/virtualization, firmware and runtime artifact downloads, Task and network for builds — a steep barrier for ordinary users (cost_benefit 1).
Security claims (hash re-verification, path traversal protection, permission stripping) are only partly visible in the provided source snippets (e.g. bbox-init seccomp, flock); most claims cannot be traced within the sample, so claim_traceability 1. CI workflows and README badges corroborate that tests/builds exist, but no test files are in the sample, so cross_source_corroboration 1. Docs mix facts with inferences (e.g. 'hardware isolation is safer') without separating them, so fact_inference_separation 1.
- Project self-declares EXPERIMENTAL; CLI flags, config format and behavior may change without notice — use cautiously in production.
- Very broad dependency surface (toolhive, docker, aws-sdk, ory and many indirect deps) with no visible dependency audit, SBOM or vulnerability mitigation in the sample.
- Runtime downloads libkrunfw firmware and prebuilt go-microvm runtime artifacts, introducing external dependency and supply-chain risk.
- Documentation inconsistencies: supported agent list and Go version requirement (README 1.26+ vs go.mod 1.27.0) disagree.
- Publisher identity is unverified; maintenance commitment and update path are unclear.
- Direct mode skips snapshot and review, writes land immediately with no undo, and only requires --yes on first use — high misuse risk.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * Update dependency NousResearch/hermes-agent to v2026.8.16 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/232 * Update dependency go-task/task to v3.53.1 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/242 * Fix SSH agent forwarding lint by @JAORMX in https://github.com/stacklok/brood-box/pull/246 * Update module github.com/gofrs/flock to v0.13.1 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/243 * Update module charm.land/lipgloss/v2 to v2.0.6 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/245 …View on GitHub ↗ -
Release notes excerpt
What's Changed * Update actions/setup-go action to v7 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/226 * Update module github.com/stacklok/toolhive-core to v0.0.30 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/225 * Update module github.com/stacklok/toolhive-core to v0.0.37 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/227 * Update module github.com/google/go-containerregistry to v0.21.8 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/229 …View on GitHub ↗ -
Release notes excerpt
What's Changed * Let Renovate manage pinned Dockerfile tool versions by @JAORMX in https://github.com/stacklok/brood-box/pull/171 * Update module github.com/stacklok/toolhive-core to v0.0.23 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/170 * Update module github.com/cedar-policy/cedar-go to v1.7.0 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/169 * Update opentelemetry-go monorepo to v1.44.0 by @renovate[bot] in https://github.com/stacklok/brood-box/pull/168 …View on GitHub ↗
FAQ
Which host environments are supported?
Will a default run modify my files directly?
Can I restrict which network hosts the VM can reach?
--allow-host to add DNS hostnames.What does it cost to use?
Is it intended for production use?
Is Brood Box open source?
Is Brood Box safe to use?
Is Brood Box still maintained?
Who makes Brood Box?
Thanks — we use this to improve the page.