# BranchBox | Work | Amidship

> Canonical URL: https://amidship.com/work/branchbox/
> Language: en-CA

BranchBox · Open-source engineering

# Isolating the whole runtime, not just the branch.

BranchBox gives each feature its own working tree and runtime boundary so developers and coding agents can work in parallel without competing for the same application environment.

v0.11.1 · Open source · MIT

The problem

## A branch can be isolated while the runtime still collides.

Parallel development gets fragile when supposedly separate work still shares ports, databases, Docker networks, environment state, or cleanup assumptions.

Git isolates source history. It does not isolate the system the code actually runs inside. As more work happens concurrently—especially with coding agents—that distinction becomes operational.

Key decision

## Parallel software work needs isolated runtime state, not just separate Git branches.

BranchBox gives each feature its own working tree and runtime boundary so developers and coding agents can work in parallel without competing for the same application environment.

**One repository**
Shared source history

- **checkout-reliability**
Feature environment

Working tree
- Runtime context
- Application state

- **billing-rules**
Feature environment

Working tree
- Runtime context
- Application state

- **search-index**
Feature environment

Working tree
- Runtime context
- Application state

One source repository can support multiple feature environments, each with its own working tree, runtime context, and application boundary.

See it in action

## The runtime boundary shows up in the CLI.

- **Start a feature environment**

![Authentic BranchBox v0.11.1 terminal capture showing branchbox --version and feature start creating the checkout-reliability worktree, branch, container runtime, isolated Compose project, and example.test feature URL.](https://amidship.com/assets/work/branchbox/evidence/01-feature-start.png)

Starting a feature creates a separate worktree, feature branch, container runtime, Compose project, application URL, and copied environment for that piece of work.

- **Inspect the active environment**

![Authentic BranchBox v0.11.1 terminal capture showing one active checkout-reliability feature with full mode, container runtime, feature branch, module status, and example.test URL.](https://amidship.com/assets/work/branchbox/evidence/02-feature-list.png)

The feature list shows the active environment and the runtime, branch, modules, and URL that belong to it.

BranchBox v0.11.1 shown in a disposable demo repository.

Architecture

## The isolation boundary, made explicit.

Per feature / isolated

### What BranchBox isolates

Each feature gets its own working tree and runtime context, with the application state that commonly makes parallel development collide kept separate by the selected runtime and project modules.

- **Working tree** Feature branch
- **Runtime / provider context** Container in this capture
- **Application / container state** Kept separate by the runtime
- **Module-created project resources** Compose · network · ports · database where selected modules apply

Deliberately shareable by default

### What BranchBox deliberately shares

BranchBox can mount selected developer authentication and coding-agent configuration into feature environments so existing tools work without repeated setup. In the current release, branchbox init --no-coding-agents disables the .codex, .claude, and .gh mounts.

- **.codex** Selected auth / configuration
- **.claude** Selected auth / configuration
- **.gh** Selected auth / configuration

Operator control

### The trade-off

BranchBox isolates the workspace and runtime state that should not collide. It does not claim that every credential or configuration file is duplicated per feature. Shared authentication is an explicit ergonomics/security choice, not hidden state.

- **branchbox init --no-coding-agents** Disables coding-agent mounts during initialization
- **Explicit boundary** Not a retroactive guarantee for every host credential or third-party tool

BranchBox lets parallel work move faster by separating the application environments that would otherwise interfere with each other, while making the remaining shared-tool boundary explicit and configurable.

Why this matters

## Parallel work needs more than separate source history.

BranchBox lets parallel work move faster by separating the application environments that would otherwise interfere with each other, while making the remaining shared-tool boundary explicit and configurable.

- Developer-platform product thinking rather than one-off automation
- Runtime and application-state isolation for parallel human and AI-assisted development
- Released Rust CLI engineering integrated with conventional application infrastructure
- An explicit, configurable boundary for shared developer authentication and coding-agent configuration
- Released teardown handling for worktrees and module-created resources
- Productizing a recurring internal engineering failure mode into reusable software

Open source

## Use it. Inspect it. Change it.

[Open BranchBox (opens in a new tab)](https://branchbox.dev/)[Inspect the source (opens in a new tab)](https://github.com/branchbox/branchbox)[Inspect release v0.11.1 (opens in a new tab)](https://github.com/branchbox/branchbox/releases/tag/v0.11.1)

[All work](https://amidship.com/work/)
[Bring us a related problem](mailto:admin@amidship.com?subject=A%20software%20problem%20to%20discuss)