First project and worktree

Add the repositoryCopy Anchor Link

Berth works with repositories that are already on the box. Register one as a location, a name for a directory on that box:

bin/berth location add my-box/app ~/work/app
bin/berth locations my-box

A path under your laptop's home is sent as ~/…, so the box reads it against its own home. A location can be any directory, but worktrees need a git repository.

In the app, Add a project takes a path on the box, a git URL or owner/repo to clone, or a new name to create an empty repository, and says what Enter will do before you press it. One repository checked out on several boxes is one project in the sidebar; see projects and worktrees.

Make a worktreeCopy Anchor Link

bin/berth worktree new my-box/app/fix-login

Berth runs git worktree add next to the repository, as ~/work/app-fix-login, on a branch named fix-login (or --branch B, from --base REF). An existing branch, locally or on origin, is checked out as it is. Then:

1. the repository's setup script runs in the new worktree, in the background, with its output in a log;
2. the worktree's services marked autostart start;
3. a worktree.created event goes to anything listening.

Worktrees made by any other tool, including plain git worktree add, show up too: berthd watches its locations.

Give it its own ports and setupCopy Anchor Link

Every worktree gets a block of ports of its own ($BERTH_PORT, $BERTH_PORT_1, …) and a set of BERTH_* variables. A repository says how to use them in .berth/config.json:

{
  "setup": "pnpm install",
  "ports": 2,
  "env": { "DATABASE_URL": "postgres://localhost/$BERTH_WORKTREE_SLUG" },
  "services": [{ "name": "web", "run": "pnpm dev --port $BERTH_PORT", "autostart": true }]
}

Commit it and every box does the same thing. For setup you'd rather not commit, use a kit or the box's own config (project config).

Open itCopy Anchor Link

A worktree's dev server is at a private URL on your laptop, served by the laptop agent's proxy through the box connection, with nothing exposed on the box:

http://fix-login.app.my-box.localhost:1377/   the worktree's own port
http://3000.my-box.localhost:1377/            any port on the box

bin/berth open my-box 3000                   # open a port in your browser
bin/berth service list my-box/app/fix-login  # the worktree's services
bin/berth edit my-box/app/fix-login          # open it in your editor, over SSH

In the app, the worktree's workspace has terminals, splits and browser tabs onto those URLs; the Run menu starts and opens its services.

NextCopy Anchor Link

Start your first agent.