shipyarddocs
shipyarddocs

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 untouched

The 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 (tracking origin); a new one starts from --base, or from what the repository has checked out.
  • A new branch from the default branch (main) starts from what origin has now. The box fetches main first and fast-forwards the local one, so the main checkout and git diff main...HEAD are current too. It only ever fast-forwards: a main checkout with uncommitted changes, or a main with commits origin doesn't have, is left as it is (the new branch then starts from origin/main, or from your local commits). A failed fetch changes nothing. Turn it off with "keep_main": false in the config, or under Main branch in Project settings.
  • --parent nests 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.created event whose origin is detected.

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 again

A 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:

URLReaches
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 ID

And for a router on the box that dispatches by host name:

berth route add '*.app.localhost' devl 8080    # Host header passed unchanged

Editors

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.

On this page