What Git Worktrees Don't Isolate (And BranchBox Does)

·https://github.com/branchbox/branchbox
repoinfrastructuredockerdevcontainersagent-loopsisolationrustsandbox

Full-stack environment isolation per worktree directly addresses the collision problem in parallel Codex/Claude Code agent runs under Restate-sandboxed workflows

BranchBox is an open-source environment isolation engine that gives every Git feature branch its own complete compute context — dedicated devcontainer, Docker network, database, ports, and .env. Not a lightweight sandbox. Each feature gets the whole stack, isolated end-to-end. The insight baked into it is that git worktrees solve code isolation but nothing else — you can have five branches checked out simultaneously and they’ll still fight over port 5432, clobber shared databases, and leak credentials across contexts. BranchBox wraps the missing layers.

The architecture is worth noting: a Rust core handles environment lifecycle, a native Swift/SwiftUI macOS app handles GUI, and a Rust agent exposes a gRPC control plane (proto definitions in agent/proto/) for programmatic control. This isn’t a shell script wrapper — it’s a proper compute management layer. Pre-built GHCR images for Rust, Rails, Node.js, and generic stacks mean containers start in seconds on first feature spin-up. Tool credentials (GitHub CLI, Claude Code, Codex, Cloudflared) are safely mounted as read-only volumes — agents inherit credentials without leaking them across worktrees.

The agent-native design is what makes this relevant beyond just parallel human development. The always-on BranchBox Agent tracks feature events, heartbeats, stack metadata, and control-plane connectivity. Agents can start worktrees, run spikes in minimal mode, apply prompt seeds, and tear environments down — all through a clean API. For joelclaw’s Restate workflow sandboxes (ADR-0217), this maps directly onto the problem of running multiple Codex or Claude Code workers against the same repo without collision. Each agent loop story could get its own BranchBox feature environment: isolated DB, isolated ports, no shared state unless explicitly mounted.

The project appears mature — CHANGELOG, proper CI, Homebrew tap, bats integration tests, and a legacy folder suggesting an earlier iteration that got rewritten. Available via brew install branchbox/tap/branchbox or the installer script. Worth evaluating against the current docker-sandbox approach for agent loop execution — especially for multi-story runs where collision between parallel Implementor workers is the primary failure mode.

Key Ideas

  • Worktrees complete the isolation story — code, DB, Docker network, ports, and env vars all scoped per feature; git worktrees alone only handle the code layer
  • Rust core + Swift macOS app + gRPC agent — serious architecture, not a shell script; the agent daemon is a first-class process with its own proto definitions
  • Shared credentials as read-only mounts — Claude Code, Codex, gh, and cloudflared credentials mount safely across worktrees without leaking
  • Pre-built GHCR images — cold start in seconds for Rust/Rails/Node.js/generic stacks; falls back to local Dockerfile build on pull failure
  • Cloudflare tunnel integration — optional per-feature public URL, useful when agents need to receive webhooks during a workflow run
  • Agent control plane over gRPC — programmatic start/stop/teardown means Restate or Inngest functions can manage BranchBox lifecycle directly
  • macOS-native GUI — SwiftUI app for feature management alongside CLI; suggests serious local-dev focus, not just CI tooling
  • Minimal mode for spikes — agents can start lightweight environments without full DB provisioning when exploration is the goal

Links

← All discoveries