{"id":47471418,"url":"https://github.com/stacklok/brood-box","last_synced_at":"2026-04-01T19:51:05.606Z","repository":{"id":344808318,"uuid":"1157363528","full_name":"stacklok/brood-box","owner":"stacklok","description":"CLI tool for running coding agents inside hardware-isolated microVMs","archived":false,"fork":false,"pushed_at":"2026-03-25T06:36:09.000Z","size":898,"stargazers_count":20,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-25T08:03:18.223Z","etag":null,"topics":["ai-agents","claude-code","codex","developer-tools","microvm","sandbox","security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacklok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T18:25:11.000Z","updated_at":"2026-03-25T06:36:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stacklok/brood-box","commit_stats":null,"previous_names":["stacklok/brood-box"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/stacklok/brood-box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Fbrood-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Fbrood-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Fbrood-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Fbrood-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacklok","download_url":"https://codeload.github.com/stacklok/brood-box/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Fbrood-box/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","codex","developer-tools","microvm","sandbox","security"],"created_at":"2026-03-25T01:00:30.554Z","updated_at":"2026-04-01T19:51:05.601Z","avatar_url":"https://github.com/stacklok.png","language":"Go","readme":"# Brood Box\n\n\u003e **Warning**\n\u003e This project is **EXPERIMENTAL**. APIs, CLI flags, config format, and behavior may change without notice between releases. Use at your own risk and please report issues.\n\nRun coding agents in hardware-isolated microVMs. Review every change before it touches your workspace.\n\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![CI](https://github.com/stacklok/brood-box/actions/workflows/ci.yaml/badge.svg)](https://github.com/stacklok/brood-box/actions/workflows/ci.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/stacklok/brood-box)](https://goreportcard.com/report/github.com/stacklok/brood-box)\n[![Repostatus: Experimental](https://www.repostatus.org/badges/latest/experimental.svg)](https://www.repostatus.org/#experimental)\n\n\u003c!-- TODO: Add a terminal recording / GIF demo here showing the full workflow --\u003e\n\n## Table of Contents\n\n- [Why?](#why)\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Egress Firewall](#egress-firewall)\n- [Supported Agents](#supported-agents)\n- [How It Works](#how-it-works)\n- [Security Model](#security-model)\n- [Documentation](#documentation)\n- [Building from Source](#building-from-source)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why?\n\nCoding agents are powerful, but they need access to your workspace, your API keys,\nand the ability to run arbitrary code. That's a lot of trust to hand over.\n\nContainers help, but they share the host kernel. One escape and you're done.\n\nEnter **Brood Box**. It boots a lightweight microVM (via [libkrun](https://github.com/containers/libkrun) and KVM),\nmounts a copy-on-write snapshot of your workspace, forwards only the secrets you\nspecify, and lets you review every file change before it lands. Hardware isolation\nwith the feel of a local terminal.\n\n```bash\nbbox claude-code\n```\n\nAnd that's it. You get a full interactive session with Claude Code running inside a\nVM. When the agent exits, you review the diff and accept or reject each file.\n\n## Features\n\n- **Hardware-isolated microVMs** -- KVM (Linux) and Hypervisor.framework (macOS) backed VMs via libkrun, not just containers\n- **Workspace snapshot \u0026 review** -- COW snapshot so the agent never touches your real files; interactive per-file review with unified diffs when it's done\n- **Multi-agent support** -- Claude Code, Codex, and OpenCode out of the box, plus custom agents via config\n- **DNS-aware egress firewall** -- Three profiles (permissive, standard, locked) control what the VM can reach\n- **MCP tool proxy** -- Automatically discovers and proxies [ToolHive](https://github.com/stacklok/toolhive) MCP servers into the VM\n- **Git integration** -- Forwards tokens and SSH agent for git operations inside the VM\n- **Ephemeral security** -- Per-session SSH keys, localhost-only connections, non-overridable security patterns for sensitive files\n- **Zero persistent state** -- Each session is fully ephemeral; nothing lingers after cleanup\n\n## Quick Start\n\n### Prerequisites\n\n- Linux with KVM support (`/dev/kvm` must be accessible), or macOS with Hypervisor.framework (Apple Silicon)\n- [Go 1.26+](https://go.dev/dl/)\n- [Task](https://taskfile.dev/) (task runner)\n- [GitHub CLI (`gh`)](https://cli.github.com/) (for downloading pre-built runtime artifacts)\n- An API key for your agent (e.g. `ANTHROPIC_API_KEY` for Claude Code)\n\n### Install from Release\n\nDownload a pre-built binary from [GitHub Releases](https://github.com/stacklok/brood-box/releases):\n\n```bash\n# Example for Linux amd64\ntar xzf bbox-linux-amd64.tar.gz\nsudo mv bbox /usr/local/bin/\n```\n\nRelease binaries are self-contained and do not require `libkrun-devel` or any system libraries.\n\n### Build from Source\n\n```bash\ntask build\n```\n\nThis downloads pre-built go-microvm runtime artifacts and embeds them into a\nself-contained `bbox` binary (pure Go, no CGO). No system `libkrun-devel`\nneeded. The binary lands in `bin/`.\n\nThe firmware (`libkrunfw`) is not embedded. It is downloaded at runtime and\ncached under `~/.cache/broodbox/firmware/`, with a system fallback if the\ndownload is unavailable.\n\n### Run\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nbbox claude-code\n```\n\nThe workflow:\n\n1. Creates a COW snapshot of your current directory\n2. Boots a microVM with the Claude Code image\n3. Drops you into an interactive terminal session\n4. When you exit, shows a per-file diff review\n5. Accepted changes are flushed back to your workspace\n\n## Usage\n\n```bash\n# Run with a specific agent\nbbox claude-code\nbbox codex\nbbox opencode\n\n# Override resources\nbbox claude-code --cpus 4 --memory 4096\n\n# Use a different workspace\nbbox claude-code --workspace /path/to/project\n\n# Enable interactive per-file review (snapshot isolation is always active)\nbbox claude-code --review\n\n# Exclude files from snapshot\nbbox claude-code --exclude \"*.log\" --exclude \"tmp/\"\n\n# Lock down egress to LLM provider only\nbbox claude-code --egress-profile locked\n\n# Allow additional egress hosts (DNS hostnames only, no IP addresses)\nbbox claude-code --allow-host \"internal-api.example.com:443\"\n\n# Disable MCP proxy\nbbox claude-code --no-mcp\n\n# Disable firmware download (use system libkrunfw only)\nbbox claude-code --no-firmware-download\n\n# Use a specific ToolHive group for MCP servers\nbbox claude-code --mcp-group \"coding-tools\"\n\n# Pass agent-specific arguments (after --)\nbbox claude-code -- --help\n\n# List available agents\nbbox list\n```\n\n## Configuration\n\nBrood Box uses a three-level config system: CLI flags \u003e per-workspace \u003e global. CLI flags always win.\n\n### Global config\n\n`~/.config/broodbox/config.yaml`:\n\n```yaml\ndefaults:\n  cpus: 4\n  memory: 4096\n  egress_profile: \"permissive\"\n\nreview:\n  enabled: true\n  exclude_patterns:\n    - \"*.log\"\n    - \"build/\"\n\nmcp:\n  enabled: true\n  group: \"default\"\n  port: 4483\n\ngit:\n  forward_token: true\n  forward_ssh_agent: true\n\nruntime:\n  firmware_download: true\n\nagents:\n  claude-code:\n    env_forward:\n      - ANTHROPIC_API_KEY\n      - CLAUDE_*\n      - GITHUB_TOKEN\n```\n\n### Per-workspace config\n\n`.broodbox.yaml` in your project root:\n\n```yaml\ndefaults:\n  cpus: 8\n  memory: 8192\n\nreview:\n  exclude_patterns:\n    - \"data/\"\n```\n\nNote that `review.enabled` is **ignored** in per-workspace config for security.\nAn untrusted repo cannot disable review on your behalf.\n\nSimilarly, `egress_profile` in per-workspace config cannot widen the global profile.\n\n### Exclude patterns\n\n`.broodboxignore` in your project root uses gitignore syntax:\n\n```gitignore\n# Exclude build artifacts\nbuild/\ndist/\n\n# But include the config\n!dist/config.json\n```\n\nSecurity-sensitive patterns (`.env*`, `*.pem`, `.ssh/`, `.aws/`, etc.) are **always excluded** and cannot be negated.\n\n## Egress Firewall\n\nEach agent comes with DNS-aware egress policies. Three profiles are available:\n\n| Profile | What it allows |\n|---|---|\n| `permissive` (default) | All outbound traffic, no restrictions |\n| `standard` | LLM provider + common dev infrastructure (GitHub, npm, PyPI, Go proxy, Docker Hub, GHCR) |\n| `locked` | LLM provider only (e.g. `api.anthropic.com` for Claude Code) |\n\n```bash\n# Lock it down\nbbox claude-code --egress-profile locked\n\n# Or open it up\nbbox claude-code --egress-profile permissive\n\n# Add specific hosts to standard profile (DNS hostnames only, no IP addresses)\nbbox claude-code --allow-host \"my-registry.example.com:443\"\n```\n\n## Supported Agents\n\n| Agent | Command | Image | Default Resources |\n|---|---|---|---|\n| Claude Code | `bbox claude-code` | `ghcr.io/stacklok/brood-box/claude-code` | 2 vCPUs, 4 GiB RAM |\n| Codex | `bbox codex` | `ghcr.io/stacklok/brood-box/codex` | 2 vCPUs, 4 GiB RAM |\n| OpenCode | `bbox opencode` | `ghcr.io/stacklok/brood-box/opencode` | 2 vCPUs, 4 GiB RAM |\n\nYou can also define custom agents in your config:\n\n```yaml\nagents:\n  my-agent:\n    image: \"ghcr.io/my-org/my-agent:latest\"\n    command: [\"my-agent-binary\"]\n    cpus: 4\n    memory: 4096\n    env_forward:\n      - MY_API_KEY\n      - MY_AGENT_*\n```\n\n## How It Works\n\n```\nbbox claude-code\n      │\n      ▼\n  Create COW snapshot of workspace\n      │\n      ▼\n  Pull OCI image, extract rootfs, inject init binary + SSH keys\n      │\n      ▼\n  Boot microVM (libkrun/KVM) with virtio-fs workspace mount\n      │\n      ▼\n  Guest boots (bbox-init as PID 1):\n    → Mount filesystems, configure networking\n    → Start embedded SSH server\n    → Wait for connection\n      │\n      ▼\n  Interactive SSH session:\n    source /etc/sandbox-env \u0026\u0026 cd /workspace \u0026\u0026 exec claude\n      │\n      ▼\n  Agent exits → VM stopped\n      │\n      ▼\n  SHA-256 diff → Interactive per-file review → Flush accepted changes\n      │\n      ▼\n  Cleanup snapshot\n```\n\nThe guest VM runs a custom Go init binary (`bbox-init`) as PID 1. No shell scripts,\nno external sshd, no iproute2. Everything the guest needs is compiled into a single\nbinary that handles boot, networking, workspace mounting, and an embedded SSH server.\n\nThe workspace snapshot uses FICLONE on Linux and `clonefile(2)` on macOS for near-instant copy-on-write cloning.\nWhen the agent is done, a SHA-256 based differ detects changes, and the review UI\nshows unified diffs for each file. Accepted changes are flushed back with hash\nre-verification to prevent TOCTOU attacks. The VM is explicitly stopped before\nreview begins, so the agent can't modify files during your review.\n\n## Security Model\n\nBrood Box's isolation is built on several layers:\n\n- **KVM hardware virtualization** -- The agent runs in a real VM, not a container with a shared kernel\n- **Ephemeral SSH keys** -- ECDSA P-256 keys generated per session, destroyed on exit\n- **Localhost-only networking** -- SSH port forwards bind to 127.0.0.1 only\n- **Non-overridable security patterns** -- Files like `.env`, `*.pem`, `.ssh/`, `.aws/` are always excluded from snapshots, even if `.broodboxignore` tries to negate them\n- **Shell-escaped environment injection** -- All forwarded values are single-quote escaped\n- **VM stopped before review** -- Prevents the agent from modifying files while you're reviewing\n- **Hash verification on flush** -- Files are re-hashed between diff and flush to catch any modifications\n- **Permission stripping** -- setuid, setgid, and sticky bits are stripped when flushing changes\n- **Path traversal protection** -- Symlinks are validated in-bounds before copying\n- **Per-workspace config restrictions** -- `review.enabled` and egress widening are ignored in `.broodbox.yaml`\n\n## Documentation\n\nDetailed documentation lives in the [`docs/`](docs/) directory:\n\n| Document | Description |\n|----------|-------------|\n| [User Guide](docs/USER_GUIDE.md) | Full CLI reference, configuration, snapshot isolation, egress firewall, MCP proxy, and troubleshooting |\n| [Architecture](docs/ARCHITECTURE.md) | DDD layers, dependency injection, VM lifecycle, guest environment, and security model |\n| [Development Guide](docs/DEVELOPMENT.md) | Prerequisites, task commands, adding agents, writing tests, and code conventions |\n| [macOS Support](docs/MACOS.md) | Apple Silicon setup, building with Homebrew libkrun, and macOS-specific troubleshooting |\n\n## Building from Source\n\n```bash\n# Build self-contained bbox (downloads + embeds go-microvm runtime)\ntask build\n\n# Build bbox + go-microvm-runner from system libkrun (requires libkrun-devel)\ntask build-dev-system\n\n# Build guest init binary\ntask build-init\n\n# Run tests\ntask test\n\n# Lint\ntask lint\n\n# Format + lint + test\ntask verify\n\n# Build guest VM images (requires docker or podman)\ntask image-all\n```\n\nAlways use `task` for building, testing, and linting. The Taskfile sets\ncritical flags, ldflags, and environment variables that raw `go` commands miss.\nSee the [Development Guide](docs/DEVELOPMENT.md) for the full command reference.\n\n## Contributing\n\nContributions are welcome! Please open an issue to discuss your idea before submitting a PR.\n\nThe project follows strict DDD (Domain-Driven Design) layered architecture:\n\n- **[Architecture overview](docs/ARCHITECTURE.md)** for understanding the layers and design decisions\n- **[Development guide](docs/DEVELOPMENT.md)** for setting up your environment, running tests, and code conventions\n\n## License\n\n[Apache-2.0](LICENSE)\n\nCopyright 2025 [Stacklok, Inc.](https://stacklok.com)\n","funding_links":[],"categories":["Agent Infrastructure","Tools","Ecosystem","Harnesses \u0026 orchestration","Security \u0026 Compliance","Sandboxing \u0026 Isolation"],"sub_categories":["Sandboxing \u0026 Isolation","Quick Setup with cc-safe-setup","Agent infrastructure"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Fbrood-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacklok%2Fbrood-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Fbrood-box/lists"}