bead

Every git worktree gets its own machine.

Keep your editor, coding agent and git on your laptop. Each worktree gets a Linux machine for its builds, tests and dev server, so parallel agents stop competing for one laptop’s ports, CPU and memory.

Start a machine for this worktree

bead worktree up

Needs the bead CLI: install it from the home page.

  1. main
  2. fix-login
  3. new-billing
Three worktrees, three machines. Each runs its own builds and its own dev server.Example branch names.

What people run on it.

Parallel coding agents

Give each Claude Code or Codex session its own worktree and its own machine. They no longer share one port 3000 or one CPU.

Tests and builds

The command runs on the worktree’s machine. Output and the exit code come back to your terminal.

bead worktree exec -- cargo test

Dev servers on localhost

The service runs on the machine and its port is forwarded to 127.0.0.1, WebSockets included.

bead worktree dev web

A link to a running branch

Send a private link to one running service. It expires after 24 hours unless you set another time, up to seven days.

bead worktree share web

Set it up once per repo.

Describe the machine in a bead.toml at the repo root and commit it. Every worktree, teammate and agent uses the same file.

  1. bead worktree up

    Creates or wakes this worktree’s machine and copies your source to it.

  2. bead worktree prepare

    Runs your own setup script when dependencies change.

  3. bead worktree exec -- cargo check

    Copies what changed, runs the command, returns its output and exit code.

  4. bead worktree dev web

    Starts the service and forwards its port to your laptop.

  5. bead worktree down

    Deletes the machine when the branch is finished.

version = 1

[template]
id = "devbox"

[machine]
size = "medium"
idle_timeout = 900

[prepare]
run = ".bead/prepare"
inputs = ["Cargo.lock", ".bead/**"]

[service.web]
run = "npm run dev"
port = 3000

What goes to the machine.

Show
  • Your laptopThe machine
  • src/, tests/copied1 changed file copied
  • Cargo.lock, bead.tomlcopiedunchanged, not sent
  • new untracked filescopiedunchanged, not sent
  • .git historystays on your laptop
  • .env filesstays; values go to the command
  • *.pem, *.keystays on your laptop
  • target/, node_modules/built on the machine, kept there

Your files, one way.

Tracked files and untracked files that git doesn’t ignore are copied from laptop to machine. Deletes are copied too. Build output and caches on the machine are left alone.

No git history, no git credentials.

The machine gets your files and an empty git repository, so old commits never leave your laptop. Scripts can read the current commit and branch from BEAD_GIT_COMMIT and BEAD_GIT_BRANCH.

Env values, never env files.

Values from your gitignored .env files are passed to the command as environment variables. They are not written to a file on the machine.

Questions.

Do I edit code on the machine?
No. You and your agent keep editing on your laptop. Each up, exec and dev copies what changed to the worktree’s machine before it runs.
Does my git history go to the machine?
No. The machine gets your files and an empty git repository, so git status works there but git log does not. No git credentials reach the machine and it never fetches from your git host.
How do my .env files get there?
Values from gitignored .env files at the repo root are passed to your command as environment variables. For a teammate or a cloud agent without those files, bead env import stores the values in your project’s encrypted vault.
Do I pay while a machine is idle?
An idle machine pauses after the idle_timeout in bead.toml and keeps its state. While paused you pay for storage only.
What if my connection drops during a command?
The command keeps running. Ask for its result with bead worktree status and the execution ID; you get the output without running it again.
Which laptops work?
macOS and Linux. On Windows, use WSL2 with the checkout on the Linux filesystem.