Run a dev server for every branch

Every agent's branch gets its own dev server and port, reloading as the agent codes. Access them via private link from a browser or your phone.

Download for macOS
Hand this to your agent
Ask me about each of these, one at a time, with a suggested default:
- Branches (the branches to preview)
- Machine (your dev box or another remote machine to run them on)
- Checkout (the repo's folder on that machine, if it has one)
- Dev server command (check package.json, e.g. npm run dev)
Skip any I've answered. Then sum up the plan in three bullets and wait for my go. My answers override the steps below.
If a wait times out, wait again, up to three times.

Run a dev server for each branch on a remote bb machine, and share each one at its own getbb.app link.
Guide: https://getbb.app/guides/remote-dev-servers

If a step fails, stop and tell me what you saw. Don't open firewall ports, send localhost links, or share ports I didn't ask for. Leave work in progress alone: don't stash, reset, or switch branches in any folder.

1. Check what's needed first. If `bb connect status` shows remote access off, ask me to turn on bb connect in Settings. If `bb machine list` doesn't show the machine, run `bb terminal create --thread "$BB_THREAD_ID" --title "Add machine" --command "bb machine create --provider manual"`, take the install command from `bb terminal output <terminal-id>`, and run it on the machine over SSH, or send it to me if you can't reach it. If the machine is a container dev environment without systemd, like Codespaces, Coder, Ona, Cloud Workstations, or an in-house container, tell me to raise its idle timeout and to add `curl -sSL <my bb address>/install.sh | sh -s -- --start --host-id <machine-id>` to its startup script, so bb comes back when it restarts.
2. Each server runs from what's committed on its branch. If a branch I named has uncommitted or unpushed changes, here or in my checkout, tell me and ask whether to commit and push them first or skip that branch.
3. If `bb project show "$BB_PROJECT_ID"` has no source on the machine, run `bb project source add "$BB_PROJECT_ID" --path <checkout> --machine <machine>` for my existing checkout, or `bb project source add "$BB_PROJECT_ID" --clone --machine <machine>` if there isn't one.
4. For each branch, start a thread on the machine that starts its own server, all at once:
   bb thread spawn --json --project "$BB_PROJECT_ID" --machine <machine> --new-environment worktree --base-branch <origin/branch, or the local branch if there's no remote> --title "<branch>" --prompt "Install dependencies if they're missing, then start this branch's dev server. Pick a free port, save it as WEB_PORT in .env.local (don't commit it), and run <dev server command> with HOST=127.0.0.1 and PORT set to that port in a bb terminal titled Dev server. Don't change the app's code. Reply with the port once it's listening, or with the error."
5. Wait for each thread with `bb thread wait` and read its port with `bb thread output`.
6. Share each port with `bb connect expose <port> --host <machine>`, and check that `bb connect shares --host <machine>` lists them all.

Reply with a table of branch, port, and link. Then offer to save these steps as a bb skill in .bb/skills/preview-branches/SKILL.md, with my machine and dev server command filled in, so next time I can just ask for it.

Steps

  1. 1Add your dev box
  2. 2Put your project on it
  3. 3Start a thread per branch
  4. 4Run each dev server
  5. 5Open it from anywhere
1

Add your dev box

Run servers on a dev box, a remote machine you already develop on. bb keeps it connected through reboots and updates.

  1. Open Settings → Machines and choose Add a machine.
  2. If bb asks how machines should reach it, sign in to bb connect, or choose Manual and enter an address the machine can reach.
  3. Choose macOS or Linux or Windows, choose Copy, and run the command on the machine over SSH.
  4. On the dev box, sign in to the agents you use, and run gh auth login so they can push and open pull requests.
  5. Check that the machine shows as Online in Settings → Machines.
2

Put your project on it

Point bb at the checkout already on your dev box, and give every branch its own ports.

  1. Open Settings → Projects and choose your project.
  2. Under Checkouts, choose Set up next to the dev box.
  3. Choose Use an existing folder and pick your checkout, or Clone from the project remote if there isn't one.

Then commit a setup script at the repo root. bb runs it in every new worktree, so each branch installs its dependencies and picks free ports. Here's an example for a pnpm project; change the install command and ports to fit yours:

Example: .bb-env-setup.sh
#!/usr/bin/env bash
set -euo pipefail
pnpm install
free_port() { node -e 'const s=require("net").createServer().listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close()})'; }
printf 'WEB_PORT=%s\nAPI_PORT=%s\n' "$(free_port)" "$(free_port)" > .env.local
3

Start a thread per branch

Each thread gets its own worktree on the machine, so servers never step on each other.

  1. Choose New thread, pick the project, and choose Worktree. If the project is on more than one machine, pick the new one.
  2. In Branch from, pick the branch, and describe the work.
  3. Repeat for each branch.
4

Run each dev server

A bb terminal runs in the thread's worktree and keeps going after you close the tab.

  1. Open the side panel (⌘ J), choose , then Start terminal.
  2. Start the server on the ports the setup script picked:
Terminal
$ set -a; . ./.env.local; set +a
$ pnpm dev --host 127.0.0.1 --port "$WEB_PORT"

Or ask the thread's agent to start it for you.

5

Open it from anywhere

bb connect gives each port a private getbb.app link, and live reload works through it.

  1. Open Settings → bb connect and choose Sign in to your bb account, if you haven't.
  2. Ask the thread's agent to share its port:
Ask the agent
Share port 3001 on this machine with bb connect and give me the link.

It replies with a link like https://my-server--3001.getbb.app. Every link is listed under Shared ports in Settings → bb connect, where you can copy it or stop sharing when the branch is done. Open each link on your phone to check its branch.

Troubleshooting

The link shows a connection error
  1. Open the thread's Dev server terminal and check that the server is still running.
  2. bb connect opens the port at 127.0.0.1, so a server on 127.0.0.1 or 0.0.0.0 works. If it only listens on ::1, start it on 127.0.0.1 at the same port.
  3. Reload the link.
Two branches fight over the same port
  1. Commit .bb-env-setup.sh from step 2, so each new worktree picks its own free ports.
  2. Start each server with the ports in its .env.local, not a hard-coded one.
  3. Worktrees made before the script need a new thread.
The thread failed while setting up its worktree
  1. Open the thread and read the .bb-env-setup.sh failed output.
  2. Fix the script, commit it, and start a new thread. bb removes a worktree whose setup fails.
  3. Make optional steps non-fatal inside the script if the worktree should open anyway.
A new worktree is missing .env or other files
  1. List them in a .worktreeinclude file at the repo root, one pattern per line.
  2. Put the files in the project's checkout on that machine. bb copies them from there into each new worktree.
  3. Start a new thread.
A machine shows as disconnected
  1. Check that its computer is on, awake, and online.
  2. In Settings → Machines, open its menu and choose Reconnect.
  3. Run the command it shows on that machine. Its threads and worktrees are kept.
My app's sign-in redirects to localhost
  1. Set the share link, like https://my-server--3001.getbb.app, as your app's base URL.
  2. Add it as an allowed redirect URL in your auth provider.
  3. Restart the dev server.
My app's cookies don't stick

bb connect drops cookies that set a Domain attribute or are named better-auth.* or bb-connect.*. Use host-only cookies with other names.

FAQ

Does live reload work through the link?

Yes. bb connect passes WebSockets through, so hot reload works as it does on localhost.

Who can open my getbb.app links?

Only you, signed in to your getbb.app account, and devices you've paired. They aren't public, so webhooks and other services can't call them. To shut off access, open Settings → bb connect and choose Turn off, or choose Disconnect on that bb in your getbb.app dashboard.

Does it work with my company VPN or Tailscale?

Yes. Your machines connect out to bb, so you don't open any ports. If your work keeps dev servers on a private network, skip the shared links and open each server over your VPN or tailnet instead.

Can my team share these servers?

No. Shared links only open for your getbb.app account, and bb is built for one person.

What should already be on my dev box?

Your repo, the tools it builds with, and any .env files. List untracked files every branch needs in a .worktreeinclude, and bb copies them from your checkout into each new worktree. bb's install command adds what bb needs.

Can I keep working in my checkout over SSH?

Yes. Agents work in their own worktrees, so your checkout, editor, and terminals stay as they are.

Does this work with Codespaces, Coder, or another cloud dev environment?
  1. Yes, including Ona, Google Cloud Workstations, Microsoft Dev Box, and in-house dev boxes. Raise the box's idle timeout first. Most stop a box when you stop typing, even while agents are working.
  2. Restart bb when the box starts. Containers don't keep bb running after a stop, so add this to the box's startup script, like Codespaces' postStartCommand, with the machine ID from bb machine list: curl -sSL https://<you>.getbb.app/install.sh | sh -s -- --start --host-id <machine-id>
  3. After a rebuild, or on a new box, paste the prompt again. Your agent adds the box over SSH and points the project at its checkout. Sign in to your agents there again, and remove the old box in Settings → Machines.
Don't have a dev box?

bb can run machines in your own Modal account. Install the Modal Sandbox plugin, then pick Modal Sandbox as the machine when you start a new thread.

How do I keep a machine from running too many agents?

The built-in Concurrency limit plugin does this by default: each machine runs one thread per processor, and new turns wait until a running thread finishes. To change a machine's limit, open Settings → Concurrency limit.

What happens to a server when I archive its thread?

The dev server and other terminals stop after the 30-second undo window. Five minutes later, bb removes the worktree if no other thread uses it. The branch is kept. Commit a .bb-env-teardown.sh to clean up anything outside the worktree, like Docker containers.

Does it cost anything? Can I keep my plan?

bb is free and open source, and bb connect is free. bb runs your agents on the subscriptions or API keys you already have. Machines you add cost what they do now.

Preview every branch

Free and open source. Bring the machines and AI plans you already have.

Download for macOSApple Silicon · Also for Linux (Alpha)bb runs on macOS, Windows, and LinuxWindows (Alpha), Intel Macs & remote machines