Brood Box is an experimental CLI tool designed to let coding agents run in hardware-isolated microVMs (micro virtual machines), rather than relying solely on container isolation. It launches lightweight virtual machines via libkrun and KVM (Linux) or Hypervisor.framework (macOS), giving agents an interactive experience similar to a local terminal while restricting the agent's access to the workspace to a copy-on-write (COW) snapshot.
The main purpose is to run coding agents safely. Agents typically need access to the workspace, API keys, and the ability to execute arbitrary code, and Brood Box reduces trust risk through hardware isolation. It supports Claude Code, Codex, and OpenCode out of the box, and custom agents can be added via configuration.
Main capabilities include: hardware-isolated microVMs, based on libkrun and KVM/Hypervisor.framework; workspace snapshots and review, where after the agent exits you can view a unified diff file by file and accept or reject changes; a DNS-aware outbound firewall, offering permissive, standard, and locked configurations to control the network accessible from the virtual machine; an MCP tool proxy, which automatically discovers and proxies ToolHive MCP servers into the virtual machine; Git integration, forwarding tokens and the SSH agent to perform Git operations inside the virtual machine; temporary security mechanisms, including per-session SSH keys, local-only connections, and a non-overridable safe mode for sensitive files; zero persistent state, with each session being fully temporary.
Usage: prebuilt binaries can be downloaded from GitHub Releases, or built from source. Building requires Task, curl, a Go environment, and an agent API key (for example, ANTHROPIC_API_KEY for Claude Code). Running bbox command creates a COW snapshot of the current directory, starts a microVM with the Claude Code image, enters an interactive terminal session, and after exiting displays a file-by-file diff review; accepted changes are flushed back to the workspace. Supports --review file-by-file interactive approval. The workspace mode defaults to snapshot mode, and you can also use --workspace-mode=direct direct mode, in which writes take effect immediately, but --review and --exclude are rejected, and first use requires --yes.
Configuration uses a three-level system: CLI flags > per-workspace configuration > global configuration. Global configuration is located at ~/.config/broodbox/config.yaml, and per-workspace configuration is at the project root .broodbox.yaml. For security, in per-workspace configuration review.enabled and workspace.mode: direct are ignored, andegress_profile also cannot relax the global configuration..broodboxignore uses gitignore syntax, but security-sensitive patterns (such as .env*、*.pem、.ssh/、.aws/ , etc.) are always excluded and cannot be negated.
Applicable scenarios: developers who need to run coding agents in an isolated environment and review their changes; teams with security concerns about agent access to the workspace, keys, and network. Limitations: the project is experimental, and the API, CLI parameters, configuration format, and behavior may change without notice; requires KVM (Linux) or Hypervisor.framework (macOS, Apple Silicon); requires an agent API key; firmware is downloaded and cached at runtime, and a system fallback is available but is not embedded.
