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)

First-run prompts (branchbox init)​

In an interactive terminal, branchbox init asks only for decisions that change behavior:

PromptWhen it appearsDefault
Move to permanent location? (Y/n)Repository is in a temporary path (for example under /tmp)Y
Continue? (y/N) (with from/to paths)Reorganization is about to move the repositoryN unless you type y
Enable Cloudflare tunnels for feature worktrees?Interactive run while tunnel config is being setCurrent config value (first run defaults to enabled)
Tunnel name prefix ...Tunnel support enabledPre-filled (branchbox)
DNS zone for tunnel hostnames ...Tunnel support enabledEmpty allowed
Provide Cloudflare API credentials now ...Tunnel support enabledUses whether credentials already exist
Cloudflare account ID / Cloudflare API tokenYou chose automated provisioningRequired
Provision tunnel for 'main' branch now?Credentials were providedYes
Service URL for tunnel ingress ...Provisioning main tunnel nowAuto-detected from compose/devcontainer

For CI or fully scripted setup, use:

branchbox init -y

This skips prompts and applies defaults.

Optional: 1Password + git bootstrap​

If branchbox init creates .devcontainer/ from BranchBox templates, it also wires:

  • .devcontainer/scripts/init-host.sh (runs via initializeCommand on host)
  • .devcontainer/scripts/setup-git.sh (runs via postStartCommand in container)
  • mounted credential files: .github-token.env, .git-signing-key, .gitconfig.env

With OP_GITHUB_REF / OP_SIGNING_KEY_REF set, opening the container can auto-refresh token/key from 1Password, configure git HTTPS credentials, and enable SSH commit signing (when key material is valid).

Important: if your repo already has a custom .devcontainer/, branchbox init currently updates workspace compatibility but does not automatically retrofit these 1Password/git hooks into your existing files.

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​