{"id":35787203,"url":"https://github.com/branchbox/branchbox","last_synced_at":"2026-01-16T05:03:28.693Z","repository":{"id":320479454,"uuid":"1081902721","full_name":"branchbox/branchbox","owner":"branchbox","description":"Parallel, isolated dev environments for humans and AI coding agents. Real containers. Real databases. Zero collisions.","archived":false,"fork":false,"pushed_at":"2026-01-11T16:11:38.000Z","size":3508,"stargazers_count":31,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T17:24:12.177Z","etag":null,"topics":["agentic-development","ai-agents","ai-development","devcontainers","docker","docker-compose","docker-networking","environment-management","isolation","llm-tools","rust-cli","vibe-coding","vibe-engineering","workflows","worktrees"],"latest_commit_sha":null,"homepage":"http://branchbox.dev/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/branchbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-23T13:04:43.000Z","updated_at":"2026-01-08T18:27:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"8cda86ed-ce7c-4f4a-b666-c5a733598224","html_url":"https://github.com/branchbox/branchbox","commit_stats":null,"previous_names":["branchbox/branchbox"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/branchbox/branchbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/branchbox%2Fbranchbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/branchbox%2Fbranchbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/branchbox%2Fbranchbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/branchbox%2Fbranchbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/branchbox","download_url":"https://codeload.github.com/branchbox/branchbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/branchbox%2Fbranchbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-development","ai-agents","ai-development","devcontainers","docker","docker-compose","docker-networking","environment-management","isolation","llm-tools","rust-cli","vibe-coding","vibe-engineering","workflows","worktrees"],"created_at":"2026-01-07T07:01:59.223Z","updated_at":"2026-01-16T05:03:28.685Z","avatar_url":"https://github.com/branchbox.png","language":"Rust","readme":"# BranchBox\n### *Parallel development for humans and AI agents — real environments, zero collisions.*\n\n[![Release](https://img.shields.io/github/v/release/branchbox/branchbox)](https://github.com/branchbox/branchbox/releases/latest)\n[![Downloads](https://img.shields.io/github/downloads/branchbox/branchbox/total)](https://github.com/branchbox/branchbox/releases)\n[![CI](https://github.com/branchbox/branchbox/workflows/CI/badge.svg)](https://github.com/branchbox/branchbox/actions)\n[![License](https://img.shields.io/github/license/branchbox/branchbox)](LICENSE)\n\n**[Website](https://branchbox.dev)** · **[Documentation](https://branchbox.dev/docs)** · **[GitHub](https://github.com/branchbox/branchbox)**\n\nBranchBox is an open-source engine for **isolated, fully provisioned development environments** designed for engineers working with AI coding agents, or anyone juggling multiple features at once.\n\nEvery feature becomes its own **self-contained workspace** with:\n\n- A dedicated Git worktree  \n- Its own devcontainer  \n- Its own Docker network  \n- Its own database  \n- Its own ports  \n- Its own environment variables  \n- Optional Cloudflare or SSH tunnels  \n- Shared tool credentials mounted safely  \n\nYou get **real dev environments**, not lightweight sandboxes.  \nYour agents get safe rooms to operate.  \nYour main workspace stays clean.\n\nIf you’ve ever run multiple features or agents in parallel and felt things colliding, leaking, or breaking — BranchBox solves that. It makes parallel development a first-class workflow.\n\n---\n\n## Why BranchBox exists\n\nModern engineering is shifting toward **agentic, parallel development**:\n\n- Humans work on one feature  \n- AI agents explore another  \n- LLMs run migrations, refactors, codegen, and experiments  \n- Several ideas progress at once  \n\nThe problem: none of our tools were built for this.\n\n- Git branches collide  \n- Docker networks \u0026 ports collide  \n- Devcontainers drift  \n- Databases clash  \n- Shared credentials leak across contexts  \n- And it’s too easy for one environment to break another\n\nBranchBox adds the missing layer:\n\n\u003e **A safe, predictable compute system where every feature has its own fully isolated, fully functional dev environment.**\n\nStart one feature or ten.  \nWork alone or with multiple agents.  \nNothing touches anything else unless you want it to.\n\n---\n\n## What BranchBox gives you\n\n### 1. True isolation  \nEvery feature gets its own:\n\n- Compose project  \n- Docker network  \n- Ports  \n- `.env` file  \n- Database  \n- Devcontainer  \n\nZero collisions. Zero shared state unless explicitly mounted.\n\n### 2. Real development environments  \nNot an agent-only sandbox — a **full stack** environment:\n\n- Rails, Node, Python, or generic  \n- Containers, Docker Compose, databases  \n- Shared credentials mounts  \n- VS Code + Cursor devcontainers  \n- Built-in adapter system for detecting stacks  \n\nIf it runs locally, BranchBox can isolate it cleanly.\n\n### 3. Parallel workflows that feel effortless  \nStart five features at once.  \nRun five containers.  \nOpen five devcontainers.  \nAgents run jobs while you code in another branch.\n\nThe mental overhead stays low, and the environments stay clean.\n\n### 4. Agent-ready by design  \nAn always-on BranchBox Agent tracks:\n\n- Feature events  \n- Heartbeats  \n- Stack metadata  \n- Control-plane connectivity  \n- macOS app integration over gRPC  \n\nAgents can safely:\n\n- Start new worktrees  \n- Run minimal-mode spikes  \n- Apply prompt seeds  \n- Tear environments down  \n- Reuse shared credentials  \n\nEverything stays observable and isolated.\n\n### 5. A workflow built from real-world usage  \nBranchBox exists because of daily engineering pain:\n\n- Running multiple projects in parallel  \n- Hitting laptop limits  \n- Letting agents work independently  \n- Needing guaranteed isolation  \n- Avoiding devcontainer drift  \n- Avoiding \"I broke main\" moments  \n\nIt’s built to support how modern development actually works — especially when humans and LLM agents collaborate.\n\n\n---\n\n## Installation\n\nBranchBox is available via **Homebrew** (recommended) or direct installation.\n\n### **macOS (Homebrew)**\n```bash\nbrew install branchbox/tap/branchbox\n```\n\n### **Linux/macOS (installer script)**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/branchbox/branchbox/main/install.sh | bash\n```\n\nThen open a new terminal or run:\n```bash\nhash -r\n```\n\n---\n\n## Quick Start\n\n```bash\n# Initialize once (creates registry, checks environment)\nbranchbox init\n\n# Start a fully isolated feature workspace\nbranchbox feature start \"Add OAuth Integration\"\n\n# Work inside the new isolated environment\ncd ../oauth-integration/\n```\n\nYour feature now has:\n\n- Its own DB  \n- Its own Docker network  \n- Its own ports  \n- Its own devcontainer  \n- Its own environment variables  \n\nPrefer a disposable sample project?\n\n```bash\n./scripts/setup-sample-workspaces.sh\nbranchbox init\nbranchbox feature start \"Demo Feature\"\n```\n\n---\n\n## Devcontainer Workflow\n\nBranchBox features work seamlessly with VS Code/Cursor devcontainers, giving each feature its own isolated Docker environment while sharing tool credentials.\n\n### Pre-built Images for Instant Startup\n\nBranchBox provides official pre-built devcontainer images for all supported stacks, published to GitHub Container Registry:\n\n| Stack | Image |\n|-------|-------|\n| Rust | `ghcr.io/branchbox/branchbox/devcontainer-rust:latest` |\n| Rails | `ghcr.io/branchbox/branchbox/devcontainer-rails:latest` |\n| Node.js | `ghcr.io/branchbox/branchbox/devcontainer-nodejs:latest` |\n| Generic | `ghcr.io/branchbox/branchbox/devcontainer-generic:latest` |\n\nWhen you run `branchbox init`, the generated `compose.yaml` references these pre-built images by default. Containers start in seconds instead of minutes—no local build required.\n\n**How it works:**\n- First run: Docker pulls the pre-built image from GHCR\n- Subsequent runs: Uses cached image instantly\n- Fallback: If pull fails, automatically builds from local Dockerfile\n\n**Override options** (in `.env` or environment):\n```bash\n# Use a custom image\nDEVCONTAINER_IMAGE=my-registry.io/my-image:tag\n\n# Control pull behavior\nDEVCONTAINER_PULL_POLICY=missing  # (default) Pull if not cached\nDEVCONTAINER_PULL_POLICY=always   # Always pull latest\nDEVCONTAINER_PULL_POLICY=build    # Always build locally\n```\n\n### Opening a Feature in a Container\n\nWhen you start a new feature, BranchBox automatically copies the `.devcontainer/` configuration from your main repository:\n\n```bash\n# In main repo\nbranchbox feature start \"Add OAuth\"\n\n# Navigate to new worktree\ncd ../myapp-oauth/\n\n# Open in VS Code/Cursor\ncode .\n```\n\n**VS Code/Cursor will prompt**: \"Reopen in Container?\"\n\nClick **\"Reopen in Container\"** and your feature will run in an isolated Docker environment with:\n- ✅ Separate Docker network (no port conflicts)\n- ✅ Isolated database (for Rails/Node.js projects)\n- ✅ Same development environment as main repo\n- ✅ Shared tool credentials (see below)\n\n### Shared Tool Credentials\n\nAll feature worktrees share authentication for common development tools, so you only need to log in once:\n\n**Supported tools:**\n- **GitHub CLI** (`gh`) - Credentials stored in `~/.config/gh/`\n- **Claude Code** (`claude`) - Session stored in `~/.claude/`\n- **Codex** (`codex`) - Config stored in `~/.codex/`\n- **Cloudflared** (`cloudflared`) - Credentials in `~/.cloudflared/`\n\n**How it works:**\n\n1. **First time** - Authenticate in your main worktree:\n   ```bash\n   cd ~/projects/myapp  # main worktree\n   code .  # Reopen in Container\n   gh auth login  # Authenticate once\n   claude login   # Authenticate once\n   ```\n\n2. **All features inherit** - Open any feature worktree:\n   ```bash\n   branchbox feature start \"new feature\"\n   cd ../myapp-new-feature\n   code .  # Reopen in Container\n   gh repo view  # Already authenticated!\n   claude chat   # Already authenticated!\n   ```\n\n3. **Credentials persist** - Stored in parent directory (`~/projects/`), mounted read-write to all containers via `SHARED_CONFIG_DIR` environment variable.\n\n**Directory structure:**\n```\n~/projects/\n├── .gh/              # Shared GitHub CLI credentials\n├── .claude/          # Shared Claude session\n├── .codex/           # Shared Codex config\n├── .cloudflared/     # Shared Cloudflare tunnel credentials\n├── myapp/            # Main worktree (mounts shared dirs)\n├── myapp-feature1/   # Feature 1 (mounts same dirs)\n└── myapp-feature2/   # Feature 2 (mounts same dirs)\n```\n\n### Troubleshooting Devcontainers\n\n**Problem**: \"Reopen in Container\" option not available\n\n**Solution**: Check that `.devcontainer/` exists in feature worktree:\n```bash\nls .devcontainer/\n# Should show: devcontainer.json  compose.yaml  Dockerfile\n```\n\nIf missing, sync from main:\n```bash\nbranchbox devcontainer sync\n```\n\n**Problem**: Container takes too long to start\n\n**Solution**: Pre-built images should start in seconds. If building locally:\n```bash\n# Check if using pre-built image\ngrep \"ghcr.io/branchbox\" .devcontainer/compose.yaml\n\n# Force pull latest pre-built image\nDEVCONTAINER_PULL_POLICY=always code .\n```\n\n**Problem**: Tools require re-authentication in each container\n\n**Solution**: Verify shared config mounts are active:\n```bash\n# Inside container\nmount | grep -E '(gh|claude|codex)'\n```\n\nCheck `SHARED_CONFIG_DIR` in `.env`:\n```bash\ngrep SHARED_CONFIG_DIR .env\n```\n\n**Problem**: Container fails to start\n\n**Solution**: Rebuild without cache:\n```bash\n# In VS Code: Cmd/Ctrl+Shift+P\n# → \"Dev Containers: Rebuild Container Without Cache\"\n```\n\n**Problem**: Need to force local Dockerfile builds (skip pre-built image)\n\n**Solution**: Use one of these approaches:\n\n```bash\n# Option 1: Set environment variable\nDEVCONTAINER_PULL_POLICY=build code .\n\n# Option 2: Use compose override file (for BranchBox development)\nCOMPOSE_FILE=compose.yaml:compose.local-build.yaml docker compose up\n\n# Option 3: Add to your .env file for persistent local builds\necho \"DEVCONTAINER_PULL_POLICY=build\" \u003e\u003e .env\n```\n\n### Upgrading Existing Projects\n\nProjects initialized before the pre-built images feature need manual updates to benefit from faster startup times.\n\n**Quick upgrade** - update your `.devcontainer/compose.yaml`:\n\n```yaml\nservices:\n  your-service:\n    # Add these lines to use pre-built image with fallback\n    image: ${DEVCONTAINER_IMAGE:-ghcr.io/branchbox/branchbox/devcontainer-\u003cstack\u003e:latest}\n    pull_policy: ${DEVCONTAINER_PULL_POLICY:-missing}\n    # Keep your existing build: section as fallback\n    build:\n      context: ..\n      dockerfile: .devcontainer/Dockerfile\n```\n\nReplace `\u003cstack\u003e` with: `rust`, `rails`, `nodejs`, or `generic`.\n\n**Rails/Node.js users**: The new templates use mise for runtime version management. If you want to adopt the new approach, re-run `branchbox init` to regenerate your `.devcontainer/` files. The templates use:\n```dockerfile\nFROM mcr.microsoft.com/devcontainers/base:debian\n# mise reads .ruby-version, .nvmrc, .node-version, .tool-versions\n```\n\nAfter updating, your next `docker compose up` or \"Reopen in Container\" will pull the pre-built image instead of building locally.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbranchbox%2Fbranchbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbranchbox%2Fbranchbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbranchbox%2Fbranchbox/lists"}