Skip to main content

Quick Start

Get BranchBox running in 2 minutes.

Install​

brew install branchbox/tap/branchbox

Initialize Your Project​

Navigate to any git repository and run:

branchbox init

BranchBox will:

  • Detect your stack (Rails, Node.js, Rust, or Generic)
  • Set up the .branchbox/ registry
  • Validate your devcontainer (if present)

Start Your First Feature​

branchbox feature start "Add user authentication"

You'll see output like:

🚀 Feature workspace ready (full)
  Feature: add-user-authentication

+------------------+------------+------------------------------------------+
| Step             | Result     | Details                                  |
+------------------+------------+------------------------------------------+
| Worktree         | ✓ ready    | ../add-user-authentication               |
| Branch           | ✓ ready    | feature/add-user-authentication          |
| Adapter          | ✓ detected | Rails · http://localhost:3000            |
| Compose project  | ✓ isolated | branchbox-add-user-authentication        |
| .env             | ✓ copied   | ../add-user-authentication/.env          |
| Modules          | ✓ ready    | 4 ok                                     |
+------------------+------------+------------------------------------------+

Work in Your Isolated Environment​

As shown in the output, the new workspace is created in the parent directory. Change into it:

cd ../add-user-authentication

You're now in a fully isolated workspace:

  • Own git branch — feature/add-user-authentication
  • Own Docker network — no port conflicts
  • Own database — no data leaks
  • Own .env — customized for this feature

Run your app, make changes, commit freely. Your main workspace is untouched.

See All Your Features​

branchbox feature list
📚 Feature registry — 2 active · 0 removed (showing 2/2)
Feature                   Status  Mode  Branch                              Updated
------------------------  ------  ----  ----------------------------------- ----------------
add-user-authentication   Active  full  feature/add-user-authentication     2025-01-07 10:30
fix-payment-bug           Active  full  feature/fix-payment-bug             2025-01-07 09:15

Clean Up When Done​

branchbox feature teardown add-user-authentication
🧹 Feature teardown finished
  Worktree removed: yes
  Branch deleted: yes

Everything is gone. Clean slate.

Next Steps​