Brood Box — Summary

Brood Box (bbox) is a CLI tool from Stacklok that runs any coding agent (Claude Code, Codex, OpenCode, Gemini, Hermes) inside a hardware-isolated microVM, providing KVM-backed isolation rather than container-based isolation. The workspace is copy-on-write-snapshotted before the agent runs, so the agent never touches real files; when the session ends, a SHA-256 diff is computed and changes are flushed back only after interactive per-file review. Security layers include an egress firewall with three profiles (permissive/standard/locked), ephemeral per-session SSH keys, automatic exclusion of sensitive file patterns, and Cedar-based MCP authorization. It also proxies ToolHive MCP servers into the VM, forwarding credentials and SSH agents without exposing them to the guest. Brood Box is not a coding agent framework itself — it sits one layer below the agent loop as an execution substrate, making it fundamentally different from all 11 seed frameworks. While seeds like superpowers, BMAD, or claude-flow augment how an agent behaves (via skills, hooks, personas), Brood Box augments where the agent runs and what it can affect, giving every agent (regardless of internal methodology) hardware-level isolation and workspace protection.

Brood Box — Overview

Origin

Brood Box was created by Stacklok, Inc. (a company focused on supply-chain and AI security) as a response to the security risks inherent in giving coding agents direct workspace access. The first public commit was in 2025, and as of May 2026 it is marked "EXPERIMENTAL" with active development.

Philosophy

The project's README states the problem directly: "Coding agents are powerful, but they need access to your workspace, your API keys, and the ability to run arbitrary code. That's a lot of trust to hand over. Containers help, but they share the host kernel. One escape and you're done."

Brood Box's answer is hardware virtualization: each agent session gets a real KVM microVM (via libkrun), not a container with a shared kernel.

Key design principles from the CLAUDE.md and ARCHITECTURE.md:

• Zero persistent state: "Each session is fully ephemeral; nothing lingers after cleanup"
• Review-first: COW workspace, diff on exit, interactive approve/reject per file
• Non-overridable security patterns: .env*, *.pem, .ssh/, .aws/ are always excluded even if .broodboxignore negates them
• Tighten-only merge: workspace-local config can only restrict, never widen, global security settings
• DDD layered architecture: strict domain/application/infrastructure separation with no I/O in domain layer

Architecture Philosophy

"Hardware isolation with the feel of a local terminal"

The workflow is designed to be a thin wrapper: bbox claude-code and you get a full interactive agent session. The VM boots from an OCI image, mounts a COW workspace via virtio-fs, and runs a custom Go PID-1 init binary that handles networking, SSH, and the agent startup command.

Brood Box — Architecture

Distribution

• Type: Standalone binary CLI (bbox) written in Go
• Install: Download pre-built release tarball from GitHub Releases and move to /usr/local/bin; or task build from source
• Build: Pure Go, CGO_ENABLED=0; the embedded go-microvm runtime was pre-compiled with CGO elsewhere. Self-contained binary with bbox-init (guest PID 1) embedded.
• Platform: Linux with /dev/kvm (KVM) or macOS Apple Silicon (Hypervisor.framework)
• Runtime deps: None at runtime except libkrunfw firmware (downloaded and cached at ~/.cache/broodbox/firmware/ on first run); no system libkrun-devel needed

Directory Tree

brood-box/
├── cmd/
│   ├── bbox/main.go        — composition root, Cobra CLI
│   └── bbox-init/          — guest VM PID 1 init binary (Linux only)
├── pkg/
│   ├── domain/             — pure types + interfaces (no I/O)
│   │   ├── agent/          — Agent value object, env forwarding
│   │   ├── config/         — Config types, merge logic
│   │   ├── vm/             — VMRunner/VM interfaces
│   │   ├── snapshot/       — FileChange, Differ, Reviewer, Flusher interfaces
│   │   ├── egress/         — DNS-aware egress policy
│   │   └── settings/       — host-to-guest settings injection interface
│   ├── sandbox/            — SandboxRunner application orchestrator
│   └── runtime/            — public factory, wires default infra for SDK consumers
├── internal/infra/
│   ├── vm/                 — go-microvm VMRunner (KVM backend)
│   ├── ssh/                — interactive PTY terminal session
│   ├── workspace/          — COW cloning (FICLONE/clonefile)
│   ├── diff/               — SHA-256 file differ
│   ├── review/             — per-file interactive reviewer + flusher
│   ├── mcp/                — ToolHive vmcp proxy + Cedar authz profiles
│   ├── exclude/            — gitignore-style pattern matching
│   └── settings/           — FSInjector (host → guest file copy)
├── images/                 — Dockerfile definitions for agent OCI images
├── docs/
│   ├── ARCHITECTURE.md
│   ├── USER_GUIDE.md
│   └── DEVELOPMENT.md
└── Taskfile.yaml           — build system (never invoke go directly)

Config Files

• ~/.config/broodbox/config.yaml — global config (CPUs, memory, egress profiles, MCP settings, agent env forwarding)
• .broodbox.yaml in workspace root — per-project overrides (tighten-only: cannot widen egress or disable review)
• .broodboxignore — gitignore-syntax exclude patterns
• Config precedence: CLI flags > per-workspace > global

Supported Agents

Custom agents can be defined in config.yaml with a custom OCI image.

Target AI Tools

Claude Code, Codex, OpenCode, Gemini CLI, Hermes, plus any custom agent — all wrapped at the execution layer, not the agent-instruction layer.

VM Execution Flow

bbox claude-code
  → Create COW snapshot (FICLONE on Linux, clonefile on macOS)
  → Pull OCI image; extract rootfs; inject bbox-init + SSH keys
  → Boot microVM (libkrun/KVM) with virtio-fs workspace mount
  → Guest: bbox-init as PID 1 → network → SSH → exec agent
  → Interactive SSH PTY session
  → Agent exits → VM stopped explicitly
  → SHA-256 diff → per-file review → flush accepted → cleanup snapshot

Brood Box — Components

CLI Commands (bbox subcommands)

CLI Flags (key, shared across agent commands)

Infrastructure Components (internal)

MCP Authorization Profiles

OCI Images (GitHub Container Registry: ghcr.io/stacklok/brood-box/)

• claude-code — Claude Code agent image
• codex — Codex agent image
• opencode — OpenCode agent image
• hermes — Hermes agent image
• gemini — Gemini CLI image

Egress Profiles

Scripts / Task Targets

Build system uses task (Taskfile.yaml):

• task build — self-contained bbox binary
• task build-init — guest PID 1 binary
• task test — go test with race detector
• task lint — golangci-lint
• task verify — fmt + lint + test
• task image-all — build all agent OCI images
• task image-push — push images to GHCR

Brood Box — Uniqueness & Positioning

differs_from_seeds

Brood Box is architecturally unlike all 11 seed frameworks. The seeds (superpowers, openspec, BMAD-METHOD, claude-flow, taskmaster-ai, agent-os, kiro, ccmemory, claude-conductor, spec-driver, spec-kit) all operate within the agent loop — they augment how an agent behaves by injecting skills, commands, hooks, MCP tools, or persona files. Brood Box operates below the agent loop: it wraps any agent in a hardware-isolated microVM, providing a security substrate that is orthogonal to whatever methodology or skill-pack the agent uses. The closest seed analogy is the isolation_mechanism field: all seeds use none, git-worktree, or container; Brood Box uses microvm. It is not a coding methodology but an execution environment — the difference is between "what should the agent do" (seeds) and "where can the agent safely do it" (Brood Box).

Positioning

Brood Box occupies the "security substrate" layer:

[ User ] → [ bbox ] → [ microVM ] → [ Claude Code / Codex / OpenCode / Gemini ]
                                              ↕
                               [ COW workspace snapshot ]

No seed framework sits at this layer. The closest comparable products are E2B and Daytona (cloud sandbox APIs), microsandbox (local microVM SDK), and Arrakis (self-hosted microVM REST API) — all in this same batch rather than in the seeds.

Distinctive Opinion

The workspace should never be modified directly by an agent; every session should be ephemeral and every change should require explicit human review before landing.

Explicit Antipatterns

• Containers with shared kernel (mentioned explicitly as insufficient)
• Per-workspace config widening global security settings
• --workspace-mode=direct as default (only allowed with explicit --yes)
• Custom Cedar policies coming from workspace config (would allow untrusted repos to define authz)
• Running raw go build / go test instead of task (builds miss critical flags)

Observable Failure Modes

1. Linux-only microVM: Requires /dev/kvm; no Windows support; macOS requires Apple Silicon
2. First-run latency: Firmware download on first use can block if network unavailable
3. go-microvm tag dependency: Release binaries for go-microvm must exist for task fetch-runtime to succeed
4. OCI image freshness: Agent images are :latest-only, rebuilt weekly; no version pinning for agent images
5. macOS entitlements: go-microvm-runner must be code-signed with assets/entitlements.plist; unsigned builds fail
6. EXPERIMENTAL status: APIs, CLI flags, config format all unstable between releases

Cross-References

• Uses ToolHive (also from Stacklok) for MCP server discovery and vmcp proxy
• Uses go-microvm (also from Stacklok) as the libkrun Go wrapper
• Cedar authorization comes from cedarpolicy.com (Amazon's Cedar policy language)