### Clone and Initialize Project

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Initial setup commands to clone the repository and run the verification pipeline.

```bash
git clone https://github.com/stacklok/brood-box.git
cd brood-box

# Install dependencies
task tidy

# Run the full verification pipeline
task verify
```

--------------------------------

### Install libkrun dependencies

Source: https://github.com/stacklok/brood-box/blob/main/docs/MACOS.md

Install the required shared libraries for go-microvm-runner via Homebrew.

```bash
brew tap slp/krun
brew install libkrun libkrunfw
```

--------------------------------

### Install Brood Box from Release

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Installs the Brood Box binary by downloading and extracting a pre-built release archive. This method does not require system libraries.

```bash
# Example for Linux amd64
tar xzf bbox-linux-amd64.tar.gz
sudo mv bbox /usr/local/bin/
```

--------------------------------

### Verification and Installation Commands

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

A command to run all verification steps (formatting, linting, testing) and a command to install the brood-box binary.

```bash
task verify
task install
```

--------------------------------

### Test Domain Layer

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Example of unit testing the domain layer using the EnvProvider interface.

```go
provider := &staticEnvProvider{vars: []string{"KEY=value"}}
result := agent.ForwardEnv([]string{"KEY"}, provider)
```

--------------------------------

### Global Configuration for Brood Box

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Example of global Brood Box configuration, including settings for interactive review and exclude patterns.

```yaml
review:
  enabled: true          # Enable interactive per-file review
  exclude_patterns:
    - "*.log"
    - "tmp/"
```

--------------------------------

### Run OpenCode Agent on Specific Project

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Start the OpenCode agent, specifying a particular workspace directory to be mounted into the VM. This allows you to work on a specific project.

```bash
bbox opencode --workspace /path/to/project
```

--------------------------------

### Per-Workspace Brood Box Configuration

Source: https://context7.com/stacklok/brood-box/llms.txt

Example of a per-workspace Brood Box configuration file (`.broodbox.yaml`). This allows project-specific overrides for default resources and review exclusion patterns.

```yaml
defaults:
  cpus: 8
  memory: "8g"

review:
  exclude_patterns:
    - "data/"
    - "*.csv"

```

--------------------------------

### Global Brood Box Configuration

Source: https://context7.com/stacklok/brood-box/llms.txt

Example of a global Brood Box configuration file (`~/.config/broodbox/config.yaml`). Customize default resources, review settings, network policies, and agent configurations.

```yaml
# Global resource defaults
defaults:
  cpus: 4
  memory: "4g"
  tmp_size: "2g"
  egress_profile: "permissive"

# Workspace snapshot review settings
review:
  enabled: true
  exclude_patterns:
    - "*.log"
    - "build/"

# Egress networking
network:
  allow_hosts:
    - name: "internal-api.example.com"
      ports: [443]

# MCP tool proxy configuration
mcp:
  enabled: true
  group: "default"
  port: 4483
  authz:
    profile: "full-access"  # Options: full-access, observe, safe-tools, custom

# Git identity and auth forwarding
git:
  forward_token: true
  forward_ssh_agent: true

# Agent settings injection
settings_import:
  enabled: true
  categories:
    settings: true
    instructions: true
    rules: true
    skills: true
    commands: true

# Credential persistence
auth:
  save_credentials: true
  seed_host_credentials: false

# Host runtime dependencies
runtime:
  firmware_download: true

# Per-agent overrides and custom agents
agents:
  claude-code:
    cpus: 4
    memory: "8g"
    env_forward:
      - ANTHROPIC_API_KEY
      - "CLAUDE_*"
      - GITHUB_TOKEN

  # Define a custom agent
  my-custom-agent:
    image: ghcr.io/my-org/my-agent:latest
    command: ["my-agent", "--interactive"]
    cpus: 2
    memory: "2g"
    env_forward:
      - MY_API_KEY

```

--------------------------------

### Define Custom Cedar Policies

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Examples of defining Cedar policies in the mcp-config.yaml file to control tool access.

```yaml
# mcp-config.yaml
authz:
  policies:
    # Let the agent discover what's available
    - 'permit(principal, action == Action::"list_tools", resource);'
    - 'permit(principal, action == Action::"list_prompts", resource);'
    - 'permit(principal, action == Action::"list_resources", resource);'
    # Allow only these specific tools
    - 'permit(principal, action == Action::"call_tool", resource == Tool::"search_code");'
    - 'permit(principal, action == Action::"call_tool", resource == Tool::"get_file_contents");'
```

```yaml
authz:
  policies:
    # Observe (list + read)
    - 'permit(principal, action == Action::"list_tools", resource);'
    - 'permit(principal, action == Action::"list_prompts", resource);'
    - 'permit(principal, action == Action::"list_resources", resource);'
    - 'permit(principal, action == Action::"get_prompt", resource);'
    - 'permit(principal, action == Action::"read_resource", resource);'
    # Safe tools (same as built-in safe-tools profile)
    - |
      permit(principal, action == Action::"call_tool", resource)
        when { resource has readOnlyHint && resource.readOnlyHint == true };
    - |
      permit(principal, action == Action::"call_tool", resource)
        when { resource has destructiveHint && resource.destructiveHint == false
            && resource has openWorldHint && resource.openWorldHint == false };
    # Plus: allow create_pull_request even though it's destructive
    - 'permit(principal, action == Action::"call_tool", resource == Tool::"create_pull_request");'
```

```yaml
authz:
  policies:
    # Allow all operations
    - 'permit(principal, action, resource);'
    # But explicitly deny this one tool (forbid overrides permit)
    - 'forbid(principal, action == Action::"call_tool", resource == Tool::"delete_repository");'
```

--------------------------------

### Inlined Custom MCP Authorization Configuration

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Example of inlining a custom MCP authorization configuration within the global config file.

```yaml
mcp:
  config:
    authz:
      policies:
        - 'permit(principal, action == Action::"list_tools", resource);'
```

--------------------------------

### Run OpenCode Agent with Review Enabled

Source: https://context7.com/stacklok/brood-box/llms.txt

Start the OpenCode agent on a specific workspace, enabling the review feature for code changes. This ensures all modifications are inspected before being applied.

```bash
# Run OpenCode on a specific workspace with review enabled
bbox opencode --workspace /path/to/project --review
```

--------------------------------

### Run Brood Box with Custom Workspace

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Starts a Brood Box session using a specified directory as the workspace. This is useful for agents that need to operate on projects located elsewhere.

```bash
bbox claude-code --workspace /path/to/project
```

--------------------------------

### Custom MCP Authorization Profile Configuration

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Example of a custom MCP authorization profile configuration using Cedar policies.

```yaml
# mcp-config.yaml
authz:
  policies:
    - 'permit(principal, action == Action::"list_tools", resource);'
    - 'permit(principal, action == Action::"call_tool", resource == Tool::"search_code");'
```

--------------------------------

### Brood Box CLI MCP Authorization Usage

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Examples of using the Brood Box CLI to set MCP authorization profiles.

```bash
bbox claude-code --mcp-authz-profile observebox claude-code --mcp-authz-profile safe-toolsbox claude-code --mcp-config /path/to/vmcp.yaml
```

--------------------------------

### Brood Box Ignore File Syntax

Source: https://context7.com/stacklok/brood-box/llms.txt

Example of a `.broodboxignore` file, using gitignore syntax to specify files and directories to exclude from workspace snapshots. Note that security patterns cannot be negated.

```gitignore
# Exclude large data files
data/
*.csv
*.parquet

# Re-include a performance-excluded directory
!vendor/

# Security patterns cannot be negated (.env, *.pem, .ssh/, etc.)

```

--------------------------------

### Run Brood Box with API Key

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Starts a Brood Box session for the Claude Code agent after exporting the necessary API key. The process includes snapshotting, VM booting, interactive session, and diff review.

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
bbox claude-code
```

--------------------------------

### Brood Box Agent List Output

Source: https://context7.com/stacklok/brood-box/llms.txt

Example output from the `bbox list` command, showing registered agents and their image references. This format is used to identify available agents.

```text
claude-code     ghcr.io/stacklok/brood-box/claude-code:latest
codex           ghcr.io/stacklok/brood-box/codex:latest
opencode        ghcr.io/stacklok/brood-box/opencode:latest
```

--------------------------------

### Initialize Configuration with Custom Path

Source: https://context7.com/stacklok/brood-box/llms.txt

Create the configuration file at a specified custom path instead of the default location. This allows for managing multiple configurations.

```bash
# Specify custom config path
bbox config init --config /path/to/config.yaml
```

--------------------------------

### Runtime and Firmware Fetching Commands

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Commands to download pre-built go-microvm runtimes and optional firmware. These are useful for setting up the necessary components for brood-box.

```bash
task fetch-runtime
task fetch-firmware
```

--------------------------------

### Troubleshoot Hypervisor and Library issues

Source: https://github.com/stacklok/brood-box/blob/main/docs/MACOS.md

Commands for manual code signing, verifying hardware virtualization support, and configuring library paths.

```bash
codesign --entitlements assets/entitlements.plist --force -s - bin/go-microvm-runner
```

```bash
sysctl kern.hv_support
# kern.hv_support: 1
```

```bash
export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
```

```go
deps := runtime.NewDefaultSandboxDeps(runtime.DefaultSandboxDepsOpts{
    LibDir: "/opt/homebrew/lib",
})
```

--------------------------------

### Debug Startup Timing

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Commands to profile startup performance and generate OpenTelemetry traces.

```bash
bbox claude-code --timings                    # Per-phase timing summary (user-facing)
bbox claude-code --trace                      # OTel trace JSON to VM data dir
bbox claude-code --trace --timings            # Both
BBOX_TRACE=1 bbox claude-code                 # Env var alternative to --trace
```

--------------------------------

### Guest Image Building Commands

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Commands to build various guest images required for running coding agents. Use these to prepare the microVM environments.

```bash
task image-base
task image-claude-code
task image-codex
task image-opencode
task image-all
```

--------------------------------

### Initialize Default Configuration

Source: https://context7.com/stacklok/brood-box/llms.txt

Create the default Brood Box configuration file (`~/.config/broodbox/config.yaml`) with documentation. This sets up basic settings for Brood Box.

```bash
# Create default config file with documentation
bbox config init
```

--------------------------------

### Develop go-microvm Locally

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Steps to link a local go-microvm dependency and rebuild the project.

```bash
# Add replace directive to go.mod (do NOT commit this)
echo 'replace github.com/stacklok/go-microvm => ../go-microvm' >> go.mod
go mod tidy

# Rebuild — must force bbox-init since it embeds go-microvm guest code
task build-init --force && task build --force
```

```bash
task build-init --force
# build bbox directly (runtime from previous version is fine)
task build
```

--------------------------------

### Override Agent Execution Command

Source: https://context7.com/stacklok/brood-box/llms.txt

Manually specify the command to execute for an agent, useful for debugging or custom agent setups. This bypasses the agent's default entrypoint.

```bash
# Override the agent command for debugging
bbox claude-code --exec /bin/bash
```

--------------------------------

### Inject Custom Dependencies in Go

Source: https://context7.com/stacklok/brood-box/llms.txt

Manually configure sandbox dependencies by creating a registry and wiring components like VM runners and workspace cloners.

```go
package main

import (
    "context"
    "log/slog"
    "os"

    infraagent "github.com/stacklok/brood-box/internal/infra/agent"
    infradiff "github.com/stacklok/brood-box/internal/infra/diff"
    infrareview "github.com/stacklok/brood-box/internal/infra/review"
    infrassh "github.com/stacklok/brood-box/internal/infra/ssh"
    infravm "github.com/stacklok/brood-box/internal/infra/vm"
    infraworkspace "github.com/stacklok/brood-box/internal/infra/workspace"
    "github.com/stacklok/brood-box/pkg/domain/agent"
    "github.com/stacklok/brood-box/pkg/sandbox"
)

func main() {
    ctx := context.Background()
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))

    // Create registry and add custom agent
    registry := infraagent.NewRegistry()
    registry.Add(agent.Agent{
        Name:          "my-agent",
        Image:         "ghcr.io/my-org/my-agent:latest",
        Command:       []string{"my-agent"},
        EnvForward:    []string{"MY_API_KEY"},
        DefaultCPUs:   2,
        DefaultMemory: 4096,
    })

    // Wire dependencies manually
    deps := sandbox.SandboxDeps{
        Registry:        registry,
        VMRunner:        infravm.NewMicroVMRunner(logger),
        SessionRunner:   infrassh.NewInteractiveSession(logger),
        Config:          &sandbox.SandboxConfig{},
        EnvProvider:     agent.NewOSEnvProvider(os.Environ),
        Logger:          logger,
        WorkspaceCloner: infraworkspace.NewFSWorkspaceCloner(
            infraworkspace.NewPlatformCloner(),
            "/tmp/snapshots",
            logger,
        ),
        Differ:   infradiff.NewFSDiffer(),
        Flusher:  infrareview.NewFSFlusher(),
        Reviewer: infrareview.NewAutoAcceptReviewer(logger, os.Stderr),
    }

    runner := sandbox.NewSandboxRunner(deps)

    opts := sandbox.RunOpts{
        Workspace: "/path/to/project",
        SessionID: "abc123",
        Snapshot: sandbox.SnapshotOpts{
            Enabled: true,
        },
    }

    if err := runner.Run(ctx, "my-agent", opts); err != nil {
        logger.Error("run failed", "error", err)
    }
}
```

--------------------------------

### Add SPDX License Headers

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Required license headers for Go and YAML files.

```go
// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
// SPDX-License-Identifier: Apache-2.0
```

```yaml
# SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
# SPDX-License-Identifier: Apache-2.0
```

--------------------------------

### Test Sandbox Layer

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Initialize a SandboxRunner with mock dependencies for testing.

```go
runner := sandbox.NewSandboxRunner(sandbox.SandboxDeps{
    Registry:    &mockRegistry{...},
    VMRunner:    &mockVMRunner{...},
    Terminal:    &mockTerminal{...},
    Config:      &sandbox.SandboxConfig{...},
    EnvProvider: &mockEnvProvider{...},
    Logger:      slog.New(slog.NewTextHandler(io.Discard, nil)),
    // Snapshot isolation deps (nil to disable review)
    WorkspaceCloner: &mockCloner{...},
    Differ:          &mockDiffer{...},
    Reviewer:        &mockReviewer{...},
    Flusher:         &mockFlusher{...},
})
```

--------------------------------

### Running a Single Test

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

This is the only exception where raw `go test` is acceptable. Use this command to run a specific test case.

```go
go test -v -race -run TestName ./path/to/package
```

--------------------------------

### Run with MCP Configuration

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Execute the command using a specific MCP configuration file.

```bash
bbox claude-code --mcp-config ./mcp-config.yaml
```

--------------------------------

### Manage Sandbox Lifecycle in Go

Source: https://context7.com/stacklok/brood-box/llms.txt

Control the sandbox lifecycle manually by invoking prepare, attach, stop, and flush operations sequentially.

```go
package main

import (
    "context"
    "fmt"
    "log/slog"
    "os"

    "github.com/stacklok/brood-box/pkg/runtime"
    "github.com/stacklok/brood-box/pkg/sandbox"
)

func main() {
    ctx := context.Background()
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))

    deps := runtime.NewDefaultSandboxDeps(runtime.DefaultSandboxDepsOpts{
        Logger: logger,
    })
    runner := sandbox.NewSandboxRunner(deps)

    opts := sandbox.RunOpts{
        Workspace: "/path/to/project",
        SessionID: "abc123",
        Snapshot: sandbox.SnapshotOpts{
            Enabled: true,
        },
    }

    // Prepare: resolve agent, create snapshot, start VM
    sb, err := runner.Prepare(ctx, "claude-code", opts)
    if err != nil {
        logger.Error("prepare failed", "error", err)
        return
    }
    defer sb.Cleanup()

    // Attach: run interactive terminal session
    terminal := createTerminal() // implementation depends on your use case
    if err := runner.Attach(ctx, sb, terminal); err != nil {
        logger.Warn("session ended", "error", err)
    }

    // Extract credentials before stopping
    runner.ExtractCredentials(sb)

    // Stop: shut down VM
    if err := runner.Stop(sb); err != nil {
        logger.Error("stop failed", "error", err)
    }

    // Compute diff and review changes
    changes, err := runner.Changes(sb)
    if err != nil {
        logger.Error("diff failed", "error", err)
        return
    }

    fmt.Printf("Detected %d file changes\n", len(changes))

    // Review changes (interactive or programmatic)
    result, err := deps.Reviewer.Review(changes)
    if err != nil {
        logger.Error("review failed", "error", err)
        return
    }

    // Flush accepted changes back to workspace
    if err := runner.Flush(sb, result.Accepted); err != nil {
        logger.Error("flush failed", "error", err)
    }
}
```

--------------------------------

### Build Brood Box from Source

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Builds the Brood Box binary from source using the Task runner. This process downloads runtime artifacts and embeds them into a pure Go binary.

```bash
task build
```

--------------------------------

### Build and Development Commands

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Use these commands to build the brood-box CLI and its components. Ensure you use the Taskfile for correct flag and dependency management.

```bash
task build
task build-init
task build-dev
task build-dev-darwin
task build-dev-system
task build-dev-system-darwin
```

--------------------------------

### Run Different Brood Box Agents

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Demonstrates how to run various supported coding agents like Codex and OpenCode using the Brood Box CLI. Ensure necessary API keys are configured.

```bash
# Run with a specific agent
bbox claude-code
bbox codex
bbox opencode
```

--------------------------------

### Force Overwrite Configuration

Source: https://context7.com/stacklok/brood-box/llms.txt

Initialize the configuration file, overwriting any existing file at the default location. Use with caution to avoid losing custom settings.

```bash
# Force overwrite existing config
bbox config init --force
```

--------------------------------

### Per-Workspace Configuration

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Configure default settings like CPU and memory, and define review-specific exclusion patterns in the .broodbox.yaml file. Note that review.enabled is ignored in this file.

```yaml
defaults:
  cpus: 4
  memory: "4g"
review:
  exclude_patterns:
    - "*.log"
```

--------------------------------

### Verify Code Changes

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Standard commands to run formatting, linting, and tests.

```bash
task fmt && task lint    # Format and lint
task test                # Full test suite with race detector
```

--------------------------------

### Visualize workspace snapshot workflow

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

A diagram illustrating the lifecycle of workspace files from snapshot creation to final review and application.

```text
Your workspace ──COW copy──▶ Snapshot directory
                                    │
                              Agent works here
                                    │
                              VM stopped
                                    │
                              Diff (SHA-256)
                                    │
                              Review per-file
                                    │
                        Accepted changes ──▶ Your workspace
```

--------------------------------

### Run Brood Box with Specific Resources

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Launches a Brood Box session, allowing customization of CPU and memory allocation for the microVM. Snapshot isolation is always active.

```bash
bbox claude-code --cpus 4 --memory 4096
```

--------------------------------

### Run Individual Verification Tasks

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Execute specific development tasks for formatting, linting, testing, and building.

```bash
task fmt          # Format code
task lint         # Check for issues
task test         # Run tests with race detector
task build        # Verify compilation
```

--------------------------------

### Initialize Sandbox Runner in Go

Source: https://context7.com/stacklok/brood-box/llms.txt

Programmatically execute Claude Code within a sandbox environment using the runtime factory.

```go
package main

import (
    "context"
    "log/slog"
    "os"

    "github.com/stacklok/brood-box/pkg/domain/agent"
    "github.com/stacklok/brood-box/pkg/runtime"
    "github.com/stacklok/brood-box/pkg/sandbox"
)

func main() {
    ctx := context.Background()
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))

    // Create sandbox runner with default infrastructure
    runner := runtime.NewDefaultSandboxRunner(runtime.DefaultSandboxDepsOpts{
        Logger: logger,
        Config: &sandbox.SandboxConfig{
            Defaults: config.DefaultsConfig{
                CPUs:   4,
                Memory: 4096,
            },
        },
    })

    // Run Claude Code
    opts := sandbox.RunOpts{
        Workspace:   "/path/to/project",
        SessionID:   "abc123",
        Snapshot: sandbox.SnapshotOpts{
            Enabled: true,
        },
    }

    if err := runner.Run(ctx, "claude-code", opts); err != nil {
        logger.Error("sandbox run failed", "error", err)
        os.Exit(1)
    }
}
```

--------------------------------

### Testing and Linting Commands

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Commands for running tests, including coverage, and performing static analysis with golangci-lint. Use these to ensure code quality and correctness.

```bash
task test
task test-coverage
task lint
task lint-fix
```

--------------------------------

### Build Brood Box Binaries

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Use `task` commands for building, testing, and linting Brood Box. These commands set critical flags, ldflags, and environment variables.

```bash
# Build self-contained bbox (downloads + embeds go-microvm runtime)
task build
```

```bash
# Build bbox + go-microvm-runner from system libkrun (requires libkrun-devel)
task build-dev-system
```

```bash
# Build guest init binary
task build-init
```

```bash
# Run tests
task test
```

```bash
# Lint
task lint
```

```bash
# Format + lint + test
task verify
```

```bash
# Build guest VM images (requires docker or podman)
task image-all
```

--------------------------------

### Run All Verification Tasks

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Execute the full suite of verification tasks in a single command.

```bash
task verify
```

--------------------------------

### Formatting and Dependency Management Commands

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Commands to format Go code using go fmt and goimports, and to manage Go module dependencies.

```bash
task fmt
task tidy
```

--------------------------------

### Log with slog

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Standard logging pattern using log/slog.

```go
s.logger.Info("starting VM", "name", cfg.Name, "cpus", cfg.CPUs)
s.logger.Error("failed to stop", "error", err)
```

--------------------------------

### Configure global Brood Box settings

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Define default resources, review policies, and environment variable forwarding in the global configuration file.

```yaml
defaults:
  cpus: 4
  memory: 4096
  egress_profile: "permissive"

review:
  enabled: true
  exclude_patterns:
    - "*.log"
    - "build/"

mcp:
  enabled: true
  group: "default"
  port: 4483

git:
  forward_token: true
  forward_ssh_agent: true

runtime:
  firmware_download: true

agents:
  claude-code:
    env_forward:
      - ANTHROPIC_API_KEY
      - CLAUDE_*
      - GITHUB_TOKEN
```

--------------------------------

### Register a New Built-in Agent

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Add a new agent configuration to the registry in internal/infra/agent/registry.go.

```go
"my-agent": {
    Name:          "my-agent",
    Image:         "ghcr.io/stacklok/brood-box/my-agent:latest",
    Command:       []string{"my-agent"},
    EnvForward:    []string{"MY_API_KEY", "MY_AGENT_*"},
    DefaultCPUs:   2,
    DefaultMemory: 2048,
},
```

--------------------------------

### Execution and Cleanup Commands

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Commands to build and run the brood-box application, and to clean up build artifacts and coverage files.

```bash
task run
task clean
```

--------------------------------

### Trigger a Release

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Commands to initiate a new release by tagging the repository.

```bash
git tag v0.0.X
git push origin v0.0.X
```

--------------------------------

### SPDX Headers for Go and YAML Files

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Required SPDX headers for Go and YAML files to ensure proper licensing and copyright information.

```go
// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
// SPDX-License-Identifier: Apache-2.0
```

--------------------------------

### Forward Environment Variables via CLI

Source: https://context7.com/stacklok/brood-box/llms.txt

Demonstrates how to forward additional environment variables to an agent using the Brood Box CLI by specifying patterns with the `--env-forward` flag.

```bash
# Forward additional env vars via CLI
bbox claude-code --env-forward MY_VAR --env-forward 'CUSTOM_*'
```

--------------------------------

### Run agent with interactive review

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Execute an agent with the review flag enabled to manually approve or reject file changes.

```bash
bbox claude-code --review
```

--------------------------------

### Configure Brood Box settings

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Define global defaults, network policies, MCP settings, and custom agent definitions in the YAML configuration file.

```yaml
# Global resource defaults (applied when agent doesn't specify its own)
defaults:
  cpus: 4
  memory: "4g"
  egress_profile: "permissive"

# Workspace snapshot review settings
review:
  enabled: true
  exclude_patterns:
    - "*.log"
    - "build/"

# Egress networking
network:
  allow_hosts:
    - name: "internal-api.example.com"
      ports: [443]

# MCP tool proxy (discovers servers from ToolHive)
mcp:
  enabled: true
  group: "default"
  port: 4483
  # Optional inline MCP config (Cedar policies and aggregation)
  # config:
  #   authz:
  #     policies:
  #       - 'permit(principal, action, resource);'
  authz:
    profile: "full-access"  # observe, safe-tools, custom

# Git identity and auth forwarding
git:
  forward_token: true       # Forward GITHUB_TOKEN/GH_TOKEN (default: true)
  forward_ssh_agent: true   # Forward SSH agent for git+ssh (default: true)

# Host runtime dependencies
runtime:
  firmware_download: true   # Download libkrunfw at runtime (default: true)

# Per-agent overrides and custom agents
agents:
  # Override built-in agent settings
  claude-code:
    env_forward:
      - ANTHROPIC_API_KEY
      - "CLAUDE_*"
      - GITHUB_TOKEN       # Forward additional vars
      - SSH_AUTH_SOCK

  # Define a custom agent
  my-custom-agent:
    image: ghcr.io/me/my-agent:latest
    command: ["my-agent", "--interactive"]
    env_forward:
      - MY_API_KEY
    cpus: 2
    memory: "1g"
```

--------------------------------

### List Available Agents

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Display a list of all agents that are available to be run with Brood Box. This command helps in discovering which agents are pre-configured.

```bash
bbox list
```

--------------------------------

### Run Brood Box

Source: https://github.com/stacklok/brood-box/blob/main/docs/MACOS.md

Execute the Brood Box binary with a specified workspace path.

```bash
bin/bbox claude-code --workspace /path/to/project
```

--------------------------------

### Build All Brood Box Images

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Execute this task to build the base OCI image and all agent-specific images (Claude Code, Codex, OpenCode) in parallel. This is useful for local development or creating custom images.

```bash
task image-all
```

--------------------------------

### Build Brood Box

Source: https://github.com/stacklok/brood-box/blob/main/docs/MACOS.md

Build commands for creating the Brood Box binary using either the embedded runtime or the system-linked runner.

```bash
task build
```

```bash
task build-dev-system-darwin
```

--------------------------------

### Run Codex Agent with Custom Resources

Source: https://context7.com/stacklok/brood-box/llms.txt

Launch the Codex agent, specifying custom CPU and memory allocations. Adjust resources based on agent requirements and system availability.

```bash
# Run Codex with custom resources
bbox codex --cpus 4 --memory 4g
```

--------------------------------

### Configure MCP Authorization via CLI

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Use the CLI to specify an MCP authorization profile and configuration file.

```bash
bbox claude-code --mcp-authz-profile custom --mcp-config /path/to/mcp-config.yaml
```

--------------------------------

### Build Individual Brood Box Images

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Use these tasks to build specific OCI images for Brood Box agents. The tasks will automatically build the base image if it's not already present.

```bash
task image-base          # Base image only
```

```bash
task image-claude-code   # Claude Code (builds base if needed)
```

```bash
task image-codex         # Codex (builds base if needed)
```

```bash
task image-opencode      # OpenCode (builds base if needed)
```

--------------------------------

### Verify KVM Access on Linux

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Check if KVM is accessible on your Linux system. If the `/dev/kvm` device is missing, you may need to load KVM modules. If permissions are denied, add your user to the 'kvm' group.

```bash
ls -la /dev/kvm
# If missing: sudo modprobe kvm && sudo modprobe kvm_intel  # or kvm_amd
# If permission denied: sudo usermod -aG kvm $USER  (then re-login)
```

--------------------------------

### Trace Hierarchy Reference

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

The expected span hierarchy for VM execution traces.

```text
bbox.Prepare → bbox.StartVM → microvm.Run → microvm.RootfsClone / microvm.SSHWaitReady
```

--------------------------------

### Execute Brood Box CLI commands

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Common commands for managing agents, egress profiles, and listing available tools.

```bash
bbox claude-code --egress-profile locked
bbox claude-code --allow-host "internal-api.example.com:443"
bbox claude-code --no-mcp
bbox claude-code --no-firmware-download
bbox claude-code --mcp-group "coding-tools"
bbox claude-code -- --help
bbox list
```

--------------------------------

### Configure per-workspace settings

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Override global defaults for specific projects using a local configuration file.

```yaml
defaults:
  cpus: 8
  memory: 8192

review:
  exclude_patterns:
    - "data/"
```

--------------------------------

### Visualize Brood Box execution flow

Source: https://github.com/stacklok/brood-box/blob/main/README.md

A representation of the lifecycle of a Brood Box agent session.

```text
bbox claude-code
      │
      ▼
  Create COW snapshot of workspace
      │
      ▼
  Pull OCI image, extract rootfs, inject init binary + SSH keys
      │
      ▼
  Boot microVM (libkrun/KVM) with virtio-fs workspace mount
      │
      ▼
  Guest boots (bbox-init as PID 1):
    → Mount filesystems, configure networking
    → Start embedded SSH server
    → Wait for connection
      │
      ▼
  Interactive SSH session:
    source /etc/sandbox-env && cd /workspace && exec claude
      │
      ▼
  Agent exits → VM stopped
      │
      ▼
  SHA-256 diff → Interactive per-file review → Flush accepted changes
      │
      ▼
  Cleanup snapshot
```

--------------------------------

### Define Dependency Injection Interfaces and Structs

Source: https://github.com/stacklok/brood-box/blob/main/docs/ARCHITECTURE.md

Uses constructor injection to manage dependencies without global state, facilitating testability with mocks.

```go
// Domain defines interfaces
type Registry interface {
    Get(name string) (Agent, error)
    List() []Agent
}

type EnvProvider interface {
    Environ() []string
}

// Sandbox layer accepts all deps via struct
type SandboxDeps struct {
    Registry    agent.Registry
    VMRunner    vm.VMRunner
    Terminal    session.TerminalSession
    Config      *sandbox.SandboxConfig
    EnvProvider agent.EnvProvider
    Logger      *slog.Logger

    // Snapshot isolation (nil when review disabled)
    WorkspaceCloner workspace.WorkspaceCloner
    Differ          snapshot.Differ
    Reviewer        snapshot.Reviewer
    Flusher         snapshot.Flusher
}

// Infra provides implementations
// vm.MicroVMRunner implements vm.VMRunner
// ssh.InteractiveSession implements session.TerminalSession
// agent.Registry implements agent.Registry
```

--------------------------------

### Wrap Errors

Source: https://github.com/stacklok/brood-box/blob/main/docs/DEVELOPMENT.md

Standard error wrapping pattern using %w.

```go
return fmt.Errorf("starting VM: %w", err)
```

--------------------------------

### Disable All Settings Injection

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Use this command-line flag to prevent any agent settings from being copied into the guest VM.

```bash
# Disable all settings injection
bbox claude-code --no-settings
```

--------------------------------

### Run Codex Agent with More Resources

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Launch the Codex agent, allocating more CPU and memory resources to the microVM. This is useful for more demanding tasks.

```bash
bbox codex --cpus 4 --memory 4g
```

--------------------------------

### Run Claude Code Agent

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Execute the Claude Code agent in the current directory. Ensure you have the necessary API keys configured.

```bash
bbox claude-code
```

--------------------------------

### Run Claude Code Agent

Source: https://context7.com/stacklok/brood-box/llms.txt

Execute the Claude Code agent in the current directory with default settings. Ensure the agent is registered and available.

```bash
# Run Claude Code in current directory with default settings
bbox claude-code
```

--------------------------------

### Image Pushing Command

Source: https://github.com/stacklok/brood-box/blob/main/CLAUDE.md

Command to push all built guest images to the GitHub Container Registry (GHCR).

```bash
task image-push
```

--------------------------------

### List Available Agents

Source: https://context7.com/stacklok/brood-box/llms.txt

Display all agents registered with Brood Box, including their names and corresponding container image URIs. Use this to verify agent availability.

```bash
# List all registered agents
bbox list
```

--------------------------------

### Configure Allowed Hosts in YAML

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Define allowed outbound hosts and their ports globally or per-workspace in a configuration YAML file under the 'network.allow_hosts' section.

```yaml
# In config.yaml
network:
  allow_hosts:
    - name: "internal-api.example.com"
      ports: [443]
```

--------------------------------

### Configure MCP Proxy Settings

Source: https://context7.com/stacklok/brood-box/llms.txt

Adjust MCP proxy behavior using command-line flags for disabling the proxy, selecting tool groups, or setting ports.

```bash
# Disable MCP proxy
bbox claude-code --no-mcp

# Use a specific ToolHive group
bbox claude-code --mcp-group "coding-tools"

# Override the proxy port
bbox claude-code --mcp-port 5000
```

--------------------------------

### Define workspace ignore patterns

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Use gitignore syntax to exclude files from the Brood Box environment.

```gitignore
# Exclude build artifacts
build/
dist/

# But include the config
!dist/config.json
```

--------------------------------

### Push Brood Box Images to GHCR

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

After logging into GHCR, use this task to build and push all Brood Box OCI images to the GitHub Container Registry. Ensure you have the necessary permissions.

```bash
# Login first
podman login ghcr.io

# Build and push all images
task image-push
```

--------------------------------

### Egress Firewall with Specific Host Allowed

Source: https://context7.com/stacklok/brood-box/llms.txt

Configure an egress profile to allow traffic to a specific host and port, in addition to the profile's default rules. This enables access to necessary internal or external services.

```bash
# Add specific hosts to any profile
bbox claude-code --egress-profile standard --allow-host "internal-api.example.com:443"
```

--------------------------------

### Set MCP Authorization Profile to Observe

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Configure the agent's MCP authorization profile to 'observe' to allow only listing and reading of MCP capabilities, restricting tool execution.

```bash
# Agent can only list and read MCP capabilitiesbox claude-code --mcp-authz-profile observe
```

--------------------------------

### Define Custom Cedar Policies

Source: https://context7.com/stacklok/brood-box/llms.txt

Configure fine-grained access control for MCP tools using YAML-based Cedar policies.

```yaml
# mcp-config.yaml
authz:
  policies:
    # Allow listing all capabilities
    - 'permit(principal, action == Action::"list_tools", resource);'
    - 'permit(principal, action == Action::"list_prompts", resource);'
    - 'permit(principal, action == Action::"list_resources", resource);'

    # Allow only specific tools
    - 'permit(principal, action == Action::"call_tool", resource == Tool::"search_code");'
    - 'permit(principal, action == Action::"call_tool", resource == Tool::"get_file_contents");'

    # Allow read-only tools based on annotations
    - |
      permit(principal, action == Action::"call_tool", resource)
        when { resource has readOnlyHint && resource.readOnlyHint == true };

aggregation:
  conflict_resolution: "prefix"  # Options: prefix, priority, manual
  prefix_format: "{workload}_{tool}"
```

--------------------------------

### Egress Firewall Standard Profile

Source: https://context7.com/stacklok/brood-box/llms.txt

Execute an agent using the 'standard' egress profile, which permits traffic to LLM providers and common development infrastructure. This balances security and usability.

```bash
# Standard - LLM provider + common dev infrastructure
bbox claude-code --egress-profile standard
```

--------------------------------

### Manage egress firewall profiles

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Control outbound network access for agents by setting profiles or allowing specific hosts.

```bash
# Lock it down
bbox claude-code --egress-profile locked

# Or open it up
bbox claude-code --egress-profile permissive

# Add specific hosts to standard profile (DNS hostnames only, no IP addresses)
bbox claude-code --allow-host "my-registry.example.com:443"
```

--------------------------------

### Define custom agents

Source: https://github.com/stacklok/brood-box/blob/main/README.md

Register custom OCI images as agents within the configuration file.

```yaml
agents:
  my-agent:
    image: "ghcr.io/my-org/my-agent:latest"
    command: ["my-agent-binary"]
    cpus: 4
    memory: 4096
    env_forward:
      - MY_API_KEY
      - MY_AGENT_*
```

--------------------------------

### Global MCP Configuration

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Set the default MCP authorization profile in the global configuration file.

```yaml
mcp:
  authz:
    profile: observe
```

--------------------------------

### Define Agent Structure in Go

Source: https://context7.com/stacklok/brood-box/llms.txt

Defines the `Agent` struct used to configure a coding agent, including its name, image, commands, environment variables, and resource limits.

```go
type Agent struct {
    Name                 string              // Unique identifier (e.g., "claude-code")
    Image                string              // OCI image reference
    Command              []string            // Entrypoint command
    EnvForward           []string            // Env patterns to forward ("API_KEY", "PREFIX_*")
    DefaultEnv           map[string]string   // Default environment variables
    NodeHeapPercent      uint32              // Limits Node.js heap (0 = disabled)
    DefaultCPUs          uint32              // Default vCPU count
    DefaultMemory        bytesize.ByteSize   // Default RAM
    DefaultTmpSize       bytesize.ByteSize   // Default /tmp size
    DefaultEgressProfile egress.ProfileName  // Default egress profile
    EgressHosts          map[egress.ProfileName][]egress.Host // Per-profile allowed hosts
    MCPConfigFormat      MCPConfigFormat     // MCP config injection format
    CredentialPaths      []string            // Paths to persist between sessions
    SettingsManifest     *settings.Manifest  // Host settings to inject
}
```

--------------------------------

### Custom Exclusions in .broodboxignore

Source: https://github.com/stacklok/brood-box/blob/main/docs/USER_GUIDE.md

Define custom exclusion and re-inclusion patterns in a .broodboxignore file using gitignore syntax. This allows for persistent, project-specific exclusions.

```gitignore
# Exclude large data files
data/
*.csv

# Re-include a performance-excluded directory
!vendor/
```