★ Open Source · MIT License · Built in Rust

Parallel development for humans and AI agents

Every feature gets its own fully isolated environment.
Real devcontainers. Real databases. Zero collisions.

macOS (Homebrew)

brew install branchbox/tap/branchbox

Linux / macOS (Script)

curl -fsSL https://raw.githubusercontent.com/branchbox/branchbox/main/install.sh | bash

⚠ The Collision Problem

Modern engineering means parallel work. Multiple features. Multiple agents. Multiple contexts. But nothing was built for this.

✕ Git branches collide when you switch contexts
✕ Docker ports & networks conflict
✕ Databases leak data across features
✕ AI agents break your main workspace
✕ Devcontainers drift out of sync
✕ Credentials scattered across environments

# The nightmare scenario
$ docker compose up
ERROR: port 3000 already in use

$ rails db:migrate
ERROR: production data corrupted

$ claude "refactor auth"
Agent modified wrong branch :(

✓ The BranchBox Fix

One command creates a complete, isolated workspace. Every feature exists in its own universe. Nothing touches anything else.

✓ Dedicated git worktree & branch
✓ Isolated Docker network & ports
✓ Separate database per feature
✓ Safe sandbox for AI agents
✓ Auto-synced devcontainer configs
✓ Shared credentials mounted everywhere

# One command. Complete isolation.
$ branchbox feature start "Add OAuth"

✓ Worktree created
✓ Devcontainer ready
✓ Database isolated
✓ Tunnel provisioned
✓ Agent launched

See the magic

Watch BranchBox create a complete isolated environment in seconds

Terminal

# Initialize BranchBox in your repo
$ branchbox init
✓ Initialized BranchBox (Rails project)

# Start an isolated feature workspace
$ branchbox feature start "OAuth Integration"

🚀 Feature workspace ready (full)
  Feature: oauth-integration

+------------------+------------+------------------------------------------+
| Step             | Result     | Details                                  |
+------------------+------------+------------------------------------------+
| Worktree         | ✓ ready    | ../oauth-integration                     |
| Branch           | ✓ ready    | feature/oauth-integration                |
| Runtime          | ✓ ready    | container                               |
| Adapter          | ✓ detected | Rails · http://localhost:3000            |
| Feature URL      | ✓ ready    | https://oauth-integration.example.com   |
| Compose project  | ✓ isolated | branchbox-oauth-integration              |
| .env             | ✓ copied   | ../oauth-integration/.env                |
| Tunnel           | ✓ online   | cloudflared (*.trycloudflare.com)       |
| Modules          | ✓ ready    | 4 ok                                     |
| Default agent    | ✓ ready    | Will launch claude via `claude`          |
+------------------+------------+------------------------------------------+

# Work in your isolated environment
$ cd ../oauth-integration
oauth-integration$ _

The workflow

From idea to isolated environment in one command

Initialize

branchbox init

One-time setup. Detects your stack (Rails, Node, Rust, etc.) and prepares the registry.

→

Start

branchbox feature start "..."

Creates worktree, devcontainer, database, network, tunnel. Everything isolated.

→

Work

cd ../feature-name

Code, test, debug. Your AI agents work here safely. Main stays pristine.

→

Teardown

branchbox feature teardown

Clean removal of worktree, containers, tunnel. Optional branch deletion.

What you get

Real development environments, not sandboxes

📦

True Isolation

Every feature gets its own git worktree, Docker network, ports, database, and environment variables. Zero shared state.

💻

Real Dev Environments

Full devcontainers with Docker Compose. Rails, Node.js, Python, Rust—if it runs locally, BranchBox isolates it.

⚡

Parallel Workflows

Run 5 features at once. 5 containers. 5 devcontainers. 5 databases. Zero mental overhead.

🤖

Agent-Ready

Built for Claude, Copilot, Cursor. Auto-launch agents, capture prompts, share credentials. Safe rooms for LLMs.

🌐

Tunnels Built In

Cloudflare tunnels for external access. Share your feature with reviewers before it’s merged.

🛠

Pluggable Isolation

Keep the account-free container workflow by default, or place the complete devcontainer and Compose stack inside an experimental Docker SBX microVM.

Built for the agentic era

AI coding agents are powerful but dangerous in shared environments. BranchBox gives each agent its own safe room to operate.

✓ Auto-launch agents — Set BRANCHBOX_DEFAULT_AGENT_CMD to spawn your agent automatically
✓ Capture context — Use --prompt to store agent hand-off instructions
✓ Shared credentials — .gh, .claude, .codex mounted across all worktrees
✓ JSON output — --json flag for scripting and automation pipelines

# Configure your default agent
$ export BRANCHBOX_DEFAULT_AGENT_CMD="claude"

# Start feature with agent context
$ branchbox feature start "Fix auth bug" \
    --prompt "Investigate login failures in auth.rs"

🚀 Feature workspace ready (full)
  Feature: fix-auth-bug
  ...
🤖 Launching claude via `claude`
   (cwd: ../fix-auth-bug)

# Agent works safely in isolated env

Full CLI reference

Everything you need to manage parallel feature development

branchbox init

Initialize project with devcontainer and BranchBox registry. Detects stack automatically.

branchbox feature start <name>

Create isolated worktree with devcontainer, database, network, and optional tunnel.

branchbox feature list

Show all features with status, tunnel info, devcontainer sync state, and agent readiness.

branchbox feature teardown <name>

Clean removal of worktree, containers, and tunnel. Handles dirty worktree detection.

branchbox devcontainer sync

Propagate devcontainer changes from main worktree to all active features.

branchbox tunnel open <name>

Provision or re-provision a Cloudflare tunnel for external feature access.

branchbox detect

Show detected stack, adapter, and enabled modules for the current project.

branchbox agent status

Show control plane connection status and telemetry for the background agent.

Key flags

--minimal Skip heavyweight modules for quick spikes

--prompt "..." Store agent hand-off context

--json Machine-readable output for automation

--complete-spec Move spec to completed on teardown

--skip-module <mod> Skip specific modules

--force Force teardown with local changes

Start building in parallel

Install BranchBox and create your first isolated feature workspace in under a minute.

brew install branchbox/tap/branchbox

Read the Docs View on GitHub