Skip to main content

Quick Start

Install BranchBox, initialize a project, and start your first feature workspace.

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).

References may contain spaces in vault, item and field names. Quote the whole reference when passing it to the CLI, for example --op-signing-key-ref 'op://Development/Git signing/private key'.

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 separate feature worktree. Depending on the configured modules, it also has:

  • Own git branch — feature/add-user-authentication
  • Compose project identity — isolates owned container resources; fixed host ports still need conflict-free configuration
  • Database naming configuration — the database module can add DATABASE_NAME to an existing .env, but your application must use it and run its own database setup
  • Own .env — customized for this feature

For the container runtime, start the devcontainer separately when you need it. Run your project's database setup and application commands, make changes, and commit in this worktree. Feature setup alone does not prove those services are running.

Optional: Use an SBX MicroVM​

The default container runtime remains local and account-free. If you have installed and signed in to Docker Sandboxes, you can place the complete devcontainer and Compose stack inside an SBX VM:

branchbox feature start "Isolated agent task" --runtime sbx
branchbox feature exec isolated-agent-task -- codex

BranchBox records the sandbox identity and actual host-port mappings for the feature. An SBX login problem affects only --runtime sbx; it does not block the default workflow. Startup errors retain an actionable error tail and exit status but omit rendered Compose configuration and redact expanded environment values. Inspect the sandbox-local devcontainer logs when more detail is needed. If you suspect an older BranchBox version copied a secret into terminal, agent, CI, or telemetry logs during a failed startup, rotate the affected credential with its provider and remove the durable log copy. Projects whose Compose stack requires .devcontainer/.cloudflared.env must configure Cloudflare credentials first; BranchBox materializes that file before SBX creation and otherwise stops before the sandbox build starts. See How It Works for provider configuration and lifecycle details.

On an x86_64 Linux/KVM execution node, use the account-free Firecracker provider after installing its pinned guest image:

branchbox feature start "Isolated local agent task" --runtime local-vm
branchbox feature exec isolated-local-agent-task -- codex

Unlike SBX, local-vm needs no Docker account. It requires /dev/kvm, Firecracker/jailer, and the digest-verified image described in How It Works.

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.

Teardown won't delete your work​

Teardown checks the worktree before it removes anything. If you left uncommitted files behind, or the branch has commits that aren't merged, it stops, changes nothing, and tells you what to do:

⚠️  Detected uncommitted changes inside ~/projects/myapp/add-user-authentication:
    • notes.txt (untracked)
    (BranchBox refuses to discard them without --discard-changes or --force)
Error: Refusing to tear down 'add-user-authentication'; nothing was removed. 1 uncommitted change in ~/projects/myapp/add-user-authentication would be lost: notes.txt (untracked). Commit or stash it, or rerun with --discard-changes to discard it. Branch 'feature/add-user-authentication' has 1 commit not merged into main; rerun with --keep-branch to keep it, or --force-delete-branch to delete it anyway.

Then choose:

  • Keep the work: commit or stash it, or push the branch and merge it first.
  • Drop the changes: --discard-changes discards the uncommitted files. It never force-deletes the branch.
  • Keep the branch: --keep-branch removes the worktree and keeps the branch for later.
  • Delete unmerged commits too: --force-delete-branch (git branch -D).

Not sure what a teardown would do? --dry-run prints the plan and changes nothing:

branchbox feature teardown add-user-authentication --dry-run

Files BranchBox generated in the worktree (such as .devcontainer/.branchbox.env) never count as your changes, and the feature's spec is moved back to the main worktree.

About --force

--force still removes the worktree whatever its state, as in earlier releases, and when the branch is deleted it uses git branch -D, so unmerged commits are deleted as well. Prefer --discard-changes with --keep-branch or --force-delete-branch, which say exactly what you want to lose.

Next Steps​