Concepts
Projects and worktrees
Locations on a box, projects across boxes, and the worktrees agents work in.
On a box, a repository is a location. In the app, the same repository across your boxes is a project. Agents work in its worktrees.
Locations
A location is a named directory on one box, usually a git repository:
berth location add devl/shop ~/work/shop
berth locations devl
berth location rm devl/shop # forgets it; files are untouchedThe box API, the CLI and hooks address things on a box by location:
shop is the repository's own checkout, shop/checkout one of its worktrees,
and devl/shop/checkout the same from the laptop.
Projects
In the app, a project is one repository wherever it is checked out. A
location on devl and one on gpu whose remotes name the same
owner/repo (or, without a remote, that share a name) are one project with
two members; you can rename, merge and split projects from the sidebar. Each
project has a default box, where new work goes unless you pick another.
The sidebar is a rail with a tile per project: its GitHub owner's picture, or a pattern made from its name. A dot on a tile turns amber when an agent in that project needs you and blue while one works. Pick a tile and that project's worktrees show beside the rail. With one project there's no rail. Settings › Appearance › Sidebar switches to a single list of every project's worktrees, grouped by project or by box, or to two columns.
Projects are an idea of the app and the laptop; boxes only know their own locations. A flow can still run for a project on every box that has it.
Worktrees
Agents work in worktrees: separate checkouts of the same repository, each on its own branch, so several agents can work at once without stepping on each other. Shipyard makes them with git, next to the repository:
~/work/shop the repository (location "shop")
~/work/shop-checkout worktree "checkout", on branch checkout
~/work/shop-fix-login worktree "fix-login"berth worktree new devl/shop/checkout [--branch B] [--base REF] [--parent NAME] [--no-setup]
berth worktree setup devl/shop/checkout [--wait]
berth worktree rm devl/shop/checkout [--force]- Keep a worktree's name to letters, digits and dashes: it becomes part of its private URL.
- The branch defaults to the name. An existing branch, local or on
origin, is checked out as it is (trackingorigin); a new one starts from--base, or from what the repository has checked out. - A new branch from the default branch (
main) starts from whatoriginhas now. The box fetchesmainfirst and fast-forwards the local one, so the main checkout andgit diff main...HEADare current too. It only ever fast-forwards: a main checkout with uncommitted changes, or amainwith commitsorigindoesn't have, is left as it is (the new branch then starts fromorigin/main, or from your local commits). A failed fetch changes nothing. Turn it off with"keep_main": falsein the config, or under Main branch in Project settings. --parentnests the new worktree under another of the location's in the sidebar, such as a stacked branch under the one it builds on. A task an agent starts, or hands its work off to, nests under that agent's worktree by itself. The main checkout is no parent.- Worktrees made by any other tool appear too, with a
worktree.createdevent whose origin isdetected.
Display names
A worktree made from a pasted link is named after it
(https-linear-app-acme). Give it a display name to show in its place:
Rename… in its menu, double-click or F2 on its sidebar row (Enter saves,
Esc cancels), right-click or F2 on its tile in the folded rail, its tab
group's menu, or its name in the status bar. When its agent's task reads as
a name, the field offers it.
It is a label only: the branch and the folder keep their names, so nothing
on the box moves, and an empty name shows the worktree's own again. The box
keeps it with the location in locations.json, so your other laptops, the
phone and the CLI see it too, and it goes with the worktree
when that is removed. The app shows it wherever the worktree appears (the
sidebar, the rail, tab groups, ⌘K and ⌘P, Home, Review, notifications, the
status bar and the window's title), with the worktree's own name beside it
where there is room and in its tooltip; ⌘K finds it by either.
berth worktree rename devl/shop/https-linear-app-acme "Cart badge after refund"
berth worktree rename devl/shop/https-linear-app-acme # its own name againA box running a berthd from before display names keeps the name on this laptop only, and says so once with Update; once the box is updated the name moves to it.
Setup and teardown
When a worktree is created, the repository's setup script runs in it (in
the background, up to 30 minutes, logged on the box); once it succeeds, its
autostart services start. Before one is removed, its services stop and the archive
script runs; if that fails, the worktree stays. Both come from
.berth/config.json, a kit, or the
box's own config for the location (berth location scripts). A
repository's own file runs only once it is
trusted on that box,
and again after it changes.
Ports and environment
Every worktree has its own block of ports, stable for its life and freed when
it is removed: $BERTH_PORT, then $BERTH_PORT_1… up to the ports the
config asks for (at most 10). Everything run in a worktree (scripts,
terminals, agents, services, hooks, exec) gets them along with
BERTH_WORKTREE_SLUG, BERTH_BRANCH and the rest; see
project config.
Pause and resume
From the Worktrees view you can pause a worktree: its running services stop and its agents are frozen where they are, using no CPU, until you resume it, which lets the agents carry on and starts the same services again. Plain shells are left alone. The resource guard does the same to idle worktrees when a box runs short of memory.
Private URLs
The laptop agent serves every box's ports at *.localhost names, through the
box connection, with nothing exposed on the box:
| URL | Reaches |
|---|---|
http://3000.devl.localhost:1377/ | Port 3000 on devl |
http://checkout.shop.devl.localhost:1377/ | The checkout worktree's dev server (its lowest listening port) |
http://shop.devl.localhost:1377/ | The main checkout's dev server |
http://checkout.shop.localhost:1377/ | The checkout worktree's dev server, when only one box has it |
http://localhost:1377/ | An index of what is reachable |
berth setup port80 on a Mac drops the :1377. Dev servers need no
configuration: the proxy presents requests to them as localhost:<port> and
rewrites their redirects back.
For a program that needs a fixed local port (a database client, say), forward one:
berth forward devl 5432 # localhost:5432 → devl:5432
berth forward devl 8080:3000 # localhost:8080 → devl:3000
berth forwards
berth unforward IDAnd for a router on the box that dispatches by host name:
berth route add '*.app.localhost' devl 8080 # Host header passed unchangedEditors
berth ssh-config --write # an SSH host per box, berth-<box>, for editors
berth edit devl/shop/checkout src/app.ts:42 # open a file at a line (--in cursor|vscode|windsurf|zed)Next: sessions and agents, what runs in a worktree.