// one box per branch

Run every branch in its own dev sandbox.

devbox starts one isolated Ubuntu sandbox for each git worktree. Each box has a desktop you can open in your browser, Pi, Chromium for OAuth, and a copy of your host gh credentials. Run branches side by side on the same ports, either locally or on Vercel.

npm @gannonh/devbox alias @gannonh/dbx license MIT os macOS · Linux runs Docker · Vercel Sandbox
zsh · devbox
$
› worktree  feat-auth → ../repo-worktrees/feat-auth
› image    devbox-base (cached)
› container dbx-feat-auth · up
› display   http://dbx-feat-auth.orb.local:6080/vnc.html
› agent    Pi ready · gh credentials copied
✓ box ready · open the display link and start coding

npx @gannonh/dbx init writes its config to your repo · full install instructions ↓

01 isolation

Run branches side by side

Each worktree gets its own sandbox and network namespace. Three branches can all bind port 5173 without sharing files, processes, or state. Uncommitted changes stay in the local worktree.

  • one sandbox and network namespace per git worktree
  • standard devcontainer format, also supported by Codespaces and Cursor
  • manage each box with --attach, --stop, or --rm
two boxes, same port
$ npx @gannonh/dbx feat-auth
› display http://dbx-feat-auth.orb.local:6080/vnc.html
$ npx @gannonh/dbx fix-cart
› display http://dbx-fix-cart.orb.local:6080/vnc.html
$ curl -sI dbx-feat-auth.orb.local:5173 | head -1
HTTP/1.1 200 OK
$ curl -sI dbx-fix-cart.orb.local:5173 | head -1
HTTP/1.1 200 OK # same port, separate networks
02 display

A desktop in your browser

Each box runs Xvfb, fluxbox, x11vnc, and noVNC. Open the desktop in a browser tab to use Electron apps and Chromium. xdg-open opens URLs in the box's Chromium. OAuth consent pages stay inside the box and remain visible over noVNC.

  • open the box's desktop in your browser
  • run Chromium and OAuth flows inside the box
  • open Vercel displays with a one-time access code
🔒 dbx-fix-cart.orb.local:6080/vnc.html
user@dbx-fix-cart: ~/workspace− ▢ ✕
$ npm test
✓ provider registry (14)
✓ worktree lifecycle (9)
✓ ports (6)
…running 29/29
fluxbox · x11vnc → your tab
03 agents

Pi included by default

devbox installs Pi and copies its configuration from your host ~/.pi, excluding sessions and npm cache. The generated provision.sh also has disabled install blocks for Claude Code and Codex. The box receives a copy of your host gh token for clone, push, and PR commands.

  • Pi enabled by default, with Claude Code and Codex blocks included
  • host gh auth token copied into the box
  • ~/.pi configuration copied without sessions or npm cache
  • dotenv values loaded only when you pass --env
dbx-feat-auth · session
user@dbx-feat-auth:/workspace$ git push -u origin feat-auth
✓ pushed with host gh credentials
user@dbx-feat-auth:/workspace$ pi
› Pi started · host configuration loaded
pi › fix the flaky checkout test and open a PR
# Pi runs in the box; the desktop stays visible over noVNC
✓ PR #42 opened from inside the box
04 providers

Choose local Docker or Vercel Sandbox

devbox saves your provider choice for this repository until you pass --provider again.

local default vercel sandbox
runs on your machine, via OrbStack / Docker a Vercel Sandbox in the cloud
reachable at <container>.orb.local:<port> HTTPS routes issued by Vercel
code source local worktree, including uncommitted changes authenticated GitHub origin, pushed commits only
display browser tab over noVNC HTTPS display link with a one-time pairing code
app ports namespaced per box with no port collisions devbox exposes approved package.json ports
05 the cli

The CLI

setup & boot

npx @gannonh/dbx initwrite .devbox/ and .devcontainer/ to this repo
npx @gannonh/dbx <branch>start a local box and open its shell
--provider vercelstart the box in a Vercel Sandbox
--env PATHload dotenv values for this run

lifecycle

--attachre-enter a running box
--stopstop it and keep the worktree and container
--rmremove the container, worktree, and branch
--listlist local devbox containers

access

--urlprint current provider routes
--openopen the first route in a browser
--passwordprint the Vercel display access code
--expose-ports 5173publish app ports on a Vercel box
06 trust

What devbox accesses

files

init writes .devbox/ and .devcontainer/. devbox stores its own state under ~/.local/state. Delete the two repo directories to undo init.

execution

The local provider runs Docker build and exec using your devcontainer config. It also runs shell hooks from .devbox/provision.sh. Both files live in your repo.

credentials

devbox copies your host gh token into the box for pushes and GitHub commands. It also copies Pi config from ~/.pi, excluding sessions and npm cache. It loads project dotenv values only when you pass --env.

network

Boxes pull base images and install project dependencies. Vercel also clones your GitHub origin and publishes the routes you approve. devbox sends no telemetry.

07 install

Install

install
# run it straight from npm
$ npx @gannonh/dbx init
$ npx @gannonh/dbx my-branch
# or install globally
$ npm i -g @gannonh/devbox
$ devbox my-branch

requirements

  • OrbStack or any Docker runtime. OrbStack provides <container>.orb.local URLs
  • @devcontainers/cli, installed with npm i -g @devcontainers/cli
  • gh authenticated on the host with gh auth login
  • git 2.45+
  • optional: host ~/.pi if you use the Pi agent