BranchBox CLI
A CLI that gives every feature its own Git worktree and environment so agents and people work in parallel without colliding
- 89 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The CLI manages Docker containers, volumes, `.env` files and shared credential mounts, and teardown removes worktrees.
Install
- Works in
Manual install
brew install branchbox/tap/branchboxThe recommended README route for macOS; Linux has an `install.sh` script.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The CLI manages Docker containers, volumes, `.env` files and shared credential mounts, and teardown removes worktrees.
This is third-party code. Review the repository files before installing.
What it does
BranchBox separates parallel feature work. The command `branchbox feature start "Add OAuth Integration"` creates a branch and a directory with its own Git worktree. Enabled modules can give each feature its own Compose project, Docker network, ports, `.env` file, database name and devcontainer, and optionally a Cloudflare tunnel. The isolation boundary is chosen with `--runtime`: `container` by default, with `sbx` (Docker Sandboxes micro-VMs) and `local-vm` (Firecracker on Linux with KVM) as experimental options. An agent runs inside the feature environment with `branchbox feature exec add-oauth -- codex`. Every command supports `--json` with a stable contract, which the native Mac app in preview and agent scripts rely on. Teardown is guarded: `branchbox feature teardown` refuses to remove a worktree with uncommitted changes.
Who it is for. Developers who run several agents and their own branches at once and suffer from clashing ports, databases and containers.
Good fit when
- An agent builds one feature while you edit another, and the working directories must not overlap
- Each branch needs its own database and its own set of ports in Docker Compose
- An agent runs inside a micro-VM boundary to limit its access
- A finished feature is torn down with one command that checks for unsaved changes
Not a fit when
- One branch and one agent, where plain `git worktree` or a simple branch is enough
- A project without Docker and no need for separate feature environments
- You want a ready cloud sandbox, while BranchBox runs on your machine
Example request
Create a separate environment for the Add OAuth Integration feature, run Codex in it and show which ports and database it gotLimitations
A successful `feature start` only reports completed setup steps and does not prove the application or database is running, so start the container and migrations separately. Fixed host ports and external databases stay shared until the project separates them in configuration. The `sbx` and `local-vm` providers are experimental: the first needs the Docker Sandboxes CLI and the second Linux x86_64 with KVM. The Mac app requires macOS 26 or later. Git-ignored files are deleted with the worktree, so copy what you need before teardown.
How to disable. Tear environments down with `branchbox feature teardown <name>` (first with `--dry-run`), then remove the CLI with `brew uninstall branchbox` or delete the binary the installer script placed.
FAQ
How do I install BranchBox?
On macOS run `brew install branchbox/tap/branchbox`. Linux and macOS also have the script `curl -fsSL https://raw.githubusercontent.com/branchbox/branchbox/main/install.sh | bash`, so read it before running.
What does branchbox init do?
It creates the registry once and checks the environment. In an interactive shell it may ask about leaving temporary directories, repository reorganization and a Cloudflare tunnel. The `-y` flag takes the defaults.
How do I run an agent inside a feature?
Run `branchbox feature exec add-oauth -- codex`. The command starts the agent in the runtime recorded for that feature.
Will teardown delete my unsaved changes?
No, it refuses without an explicit flag. Discarding changes needs `--discard-changes`, the branch needs `--keep-branch` or `--force-delete-branch`, and `--dry-run` shows the plan.
Does BranchBox have a GUI?
There is a preview Mac app that works on top of the same CLI through `--json`. It needs macOS 26 or later and `branchbox` 0.13.4 or newer.
Discussion
No questions or reviews yet.
Related
CLI toolsA Docker sandbox for coding agents: a Debian image with Copilot CLI, Codex and Pi, and SSH, RDP and Docker enabled by flags.
AgentBox runs Claude Code, Codex and Open Code in separate virtual machines on your PC, a self-hosted server or a cloud.
ExitBox runs Claude, Codex, Cursor and other agents in rootless containers: a domain allowlist and secrets in an encrypted vault.
ArcBox runs Claude Code in a disposable microVM on a Mac: its own kernel, an empty workspace and a start in about a second
Runs each agent stage in its own micro-VM: Claude, Codex, Ollama or any CLI, with OTLP tracing
Container by Aerovato
Container
A CLI for persistent per-project Linux workspaces in Docker or Podman that keep the agent away from the rest of your system
README in short
The README explains why parallel agent work breaks ports, databases and containers, lists isolation features, and gives Homebrew and script installs, a quick start and a description of the runtime providers.