Brood Box

Run coding agents in hardware-isolated microVMs and review workspace changes before they are applied.

Stars
★ 81
Last updated
today
License
Apache-2.0
Primary language
Go

At a glance

How it runs
CLI
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
KVM on Linux or Hypervisor.framework on Apple Silicon macOSGo 1.26+TaskcurlAPI key for the selected coding agentShell / CLINetwork accessLocal filesystemMCP Server
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)

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.

  1. Developers who want Claude Code to work on a project copy inside a real VM and want to inspect changes before applying them.
  2. Engineering teams using Codex, OpenCode, Hermes, or Gemini CLI that want to run them through the same bbox CLI workflow.
  3. Security engineers who need to set agent egress access to permissive, standard, or locked profiles.
  4. Developers who need Git access inside the VM and want to choose whether to forward a token or SSH agent.
  5. 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 build

How 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-code

Use --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?

Pros
  • 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.
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
53/ 100 5-point scale 2.7 / 5
Trust 18/29
Reliability 6/14
Adaptability 9/18
Convention 10/18
Effectiveness 7/13
Verifiability 3/8
Why each dimension lost points
Trust18 / 29 · 3.1/5

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.

Reliability6 / 14 · 2.1/5

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.

Adaptability9 / 18 · 2.5/5

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).

Convention10 / 18 · 2.8/5

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).

Effectiveness7 / 13 · 2.7/5

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).

Verifiability3 / 8 · 1.9/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 495757264810
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/brood-box.svg)](https://followagents.com/en/agents/brood-box)
<a href="https://followagents.com/en/agents/brood-box"><img src="https://followagents.com/badge/brood-box.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.0.25
    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 ↗
  2. v0.0.24
    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 ↗
  3. v0.0.23
    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?
The README lists Linux with accessible KVM and Apple Silicon macOS using Hypervisor.framework.
Will a default run modify my files directly?
By default, the agent works on a copy-on-write workspace snapshot. You review changes after it exits, and accepted changes are flushed back. Direct mode writes to the workspace immediately.
Can I restrict which network hosts the VM can reach?
Yes. Choose permissive, standard, or locked egress, and use --allow-host to add DNS hostnames.
What does it cost to use?
The README does not state whether Brood Box itself is charged for; running an agent requires an API key, but the provided material does not state its price.
Is it intended for production use?
The project is explicitly marked experimental and warns that its APIs, CLI flags, configuration format, and behavior may change.
Is Brood Box open source?
Yes. The source code is on GitHub (stacklok/brood-box) under the Apache-2.0 licence.
Is Brood Box safe to use?
FollowAgents' FARS review (Nov 11, 2026) scored Brood Box 18/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is Brood Box still maintained?
Yes. The latest commit on GitHub is from 2026-11-20, within the last 30 days. The latest release is v0.0.25 (2026-09-14).
Who makes Brood Box?
Brood Box is published on GitHub by the account stacklok. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts