Guides
Kits
Set a project up the same way on every box, and share it as a link.
A kit sets a project up the same way on every box, and travels as a link. It packages what a project needs around its code: setup and teardown scripts, environment, ports, services such as dev servers, hooks, agent presets, and the tools it requires.
Use a kit for setup you cannot or should not commit to the repository: a
public repository with your team's internal setup, a personal workflow, or
one setup shared by several repositories. A team that owns the repository
can commit .berth/config.json instead; a kit adds
to that.
Using one
berth kit add https://github.com/acme/kits/tree/main/shop-dev # shows what it does, then asks
berth kit show shop-dev # everything it does, every file it carries
berth kit apply shop-dev devl/shop gpu/shop # install on projects on any box
berth kit list # where each is installed, and if it is out of date
berth kit update shop-dev && berth kit apply shop-dev devl/shop # take a newer version
berth kit remove devl/shop # uninstall from a project
berth kit rm shop-dev # forget it on this laptopIn the app, Kits (under More in the sidebar) lists the kits you
added and the projects each is applied to, marking one that runs an older
version. Open a berth://kit?src=<link> link, or use Add from link
there. Either way you see everything the kit will do, every file it
carries, and where it came from, before anything is kept or run. Projects
whose repository matches the kit are selected for you.


A link can be:
- a git repository:
https://github.com/acme/shop-kit - a folder in one:
https://github.com/acme/kits/tree/main/shop-dev, orURL#shop-dev, with@reffor a branch or tag - a gist, for a kit that fits in one
kit.json - a URL to a
kit.json - a folder on this laptop, as an absolute path or one starting with
~
A link to GitHub, a gist, GitLab, Bitbucket or Codeberg works without
https:// (berth kit add github.com/acme/shop-kit). Git links are fetched
over https, http, ssh or git only.
Shipyard remembers the link and the commit, so update fetches the newest
version and the app flags projects running an older one. Kits you add live
in ~/.berth/kits/ on the laptop.
Writing one
shop-dev/
kit.json
scripts/
setup.sh
archive.sh{
"id": "shop-dev",
"name": "Shop development",
"description": "Each worktree gets its own database, ports and dev server.",
"version": "3",
"match": { "slug": "acme/shop" },
"requires": [
{ "tool": "psql", "hint": "sudo apt install postgresql-client" },
{ "tool": "pnpm" }
],
"config": {
"setup": "$BERTH_KIT_DIR/scripts/setup.sh",
"archive": "$BERTH_KIT_DIR/scripts/archive.sh",
"ports": 3,
"env": { "DATABASE_URL": "postgres://localhost/shop_$BERTH_WORKTREE_SLUG" },
"services": [{ "name": "web", "run": "pnpm dev --port $BERTH_PORT", "autostart": true, "terminal": true, "title": "Next.js" }]
}
}config is the same as a repository's .berth/config.json; see
project config and every field in
the config reference. A kit's files are copied to
each box it is applied to, and $BERTH_KIT_DIR is where they are, so its
scripts can run from there. Scripts starting with #! are made executable.
A small kit can carry its files inside kit.json under
"files": {"scripts/setup.sh": "…"}.
The web service above has "terminal": true, so it runs in a terminal of
its own: a tab named after its title opens when its worktree does, with
the dev server's output in it. Ctrl-C in the tab stops it, and Start runs it
again there; closing the tab only hides it (Show terminal in the Run
menu brings it back). See
services in a terminal.


Keep secrets out of a kit: give env a reference such as
op://dev/shop-db/password and each box reads it from 1Password when a
worktree needs it, so the kit can be shared, even publicly. See
secrets; a kit that uses op:// should list
{ "tool": "op" } in requires.
requires lists tools a box needs. A missing one is reported when the kit
is applied, not refused, since a setup script may install it.
match.slug names the repository a kit is for, as owner/repo. It is
compared, ignoring case, with each project's slug, which comes from its
origin remote (git@github.com:acme/shop.git is acme/shop).
Matching projects are picked for you when you review the kit, and adding
such a project to a box (or cloning it onto another) offers to apply the
kit. It only suggests: you can apply a kit to any project.
berth kit save devl/shop my-kit turns how a project is set up on a box into
a kit in ~/.berth/kits/my-kit/; push that folder to a git repository to
share it.
A kit in a repository of its own is that folder at the repository's top:
kit.json and the scripts it runs. Add it with its link, such as
berth kit add github.com/acme/berth-kit-web, pinned to a commit with
@<sha>. A team's kits can also live in its
.berth repository, next to team.json.
How it applies
On each project a kit is its own layer: the repository's
.berth/config.json, then the kit, then the box's own config for the
project. The box's own settings always win, so a teammate can adjust one
value without forking the kit, and updating or removing the kit never
touches either of the other layers. A project has at most one kit.
That includes flows: a kit's flows run on every box
it is applied to, for that project's worktrees, and show in Automations
marked From kit. A flow with the same id replaces the repository's, and
a box's own flow with that id replaces the kit's.
A plugin can ship kits by listing their folders under "kits" in its
berth-plugin.json.
Personas: logging in as a dev user
Most pages worth checking are behind a login. A kit can name the dev users a worktree can be logged in as, and a script that logs one in, so you, an agent, or a visual diff open a worktree as "the Pro user" in one step:
{
"id": "shop-dev",
"name": "Shop development",
"config": {
"login": {
"script": "scripts/login.sh",
"users": [
"pro@acme.test",
{ "email": "admin@acme.test", "label": "Team admin" },
{ "email": "free@acme.test", "label": "Free user" }
],
"any": false
}
}
}scriptis a path inside the kit's folder (for a repository's.berth/config.json, inside its.berth/folder). It runs in the worktree, with the worktree's environment ($BERTH_PORT,$BERTH_URL, itsDATABASE_URL…) andBERTH_LOGIN_EMAIL, against the worktree's own dev server and database. The email is only ever an environment variable, never part of a command line.usersare emails, or{ "email", "label" }. People see the label.any:truelets a link or a command name any valid email, not only the listed ones. It isfalseunless you say so.
login can also sit at the top of kit.json, next to config.
What the script prints
One JSON object on stdout:
{ "cookies": [{ "name": "session", "value": "…", "httpOnly": true, "sameSite": "Lax" }], "redirect": "/dashboard" }Each cookie takes name and value, and optionally path, httpOnly,
secure, sameSite (Lax, Strict or None) and maxAge (seconds).
There is no domain: a cookie is always set for the worktree's own address
and no other. redirect is where to go when nobody asked for a page. Output
that isn't exactly this, more than 64 KB of it, a non-zero exit, or more than
30 seconds is an error, and the error never quotes what the script printed.
Write anything else (progress, a reason it failed) to stderr, which is
dropped.
A script for an app with a credentials endpoint (POST /api/auth/login,
which sets a session cookie):
#!/bin/sh
# Logs the worktree's own dev server in as $BERTH_LOGIN_EMAIL and prints
# the session it set. Every seeded user has the password acme-dev.
set -eu
jar=$(mktemp)
trap 'rm -f "$jar"' EXIT
body=$(printf '{"email":"%s","password":"%s"}' "$BERTH_LOGIN_EMAIL" "${ACME_DEV_PASSWORD:-acme-dev}")
curl -fsS -o /dev/null -c "$jar" -H 'content-type: application/json' \
--data "$body" "http://localhost:$BERTH_PORT/api/auth/login"
session=$(awk -F '\t' '$6 == "session" { print $7 }' "$jar")
[ -n "$session" ] || { echo "the app set no session cookie" >&2; exit 1; }
printf '{"cookies":[{"name":"session","value":"%s","httpOnly":true,"sameSite":"Lax"}],"redirect":"/dashboard"}\n' "$session"The users have to exist in the worktree's database: seed them in the kit's
setup script, or let the login script create one it doesn't find.
Logging in
- In the app: the Browser tab's Log in as… menu, next to the address, lists the worktree's users and logs the tab in, staying on the page it shows. ⌘K has Log in as Pro user for each. The project's settings show the login read-only, under Login users.
- In any browser on your laptop: open
http://fix-x.shop.devl.localhost:1377/__berth/login?as=pro%40acme.test&next=/orders(the main checkout:shop.devl.localhost). The laptop runs the worktree's login on its box, answers with the cookies for that address only, and sends you on tonext. - An agent:
berthd browser open --as pro@acme.test --path /orderslogs the agent browser in the same way. - A review link:
berth://review?repo=acme/shop&pr=42&as=pro@acme.test&path=/ordersopens a teammate's PR on your box logged in as that user, at that page, when this login lists them. See review a PR. - A visual diff:
berthd shots compare --as pro@acme.testlogs both sides in, each with its own login, since the worktree and main each have their own dev server and database. See visual diffs.
What keeps it safe
- Only config you trust names users. A login comes from the kit, the
box's own config, or the repository's
.berth/config.jsonin the main checkout once trusted, never from a worktree's own checkout: a pull request can't add a user or change the script. - Only you start a login. The
/__berth/loginroute takesGETfrom your own laptop, and only when nothing else started it: a request another site or another worktree's page sent (by itsOrigin, itsReferer, orSec-Fetch-Site) is refused. It is the laptop's own: it never reaches the dev server. nextstays on the worktree. Anything that isn't a plain path, such as//evil.example,https://…or/\evil.example, encoded or not, goes to/instead.- Emails are plain addresses.
a@b.c; rm -rf /or anything with a space, a quote or a$is refused before anything runs, and with"any": falseso is an email the config doesn't list. - Sessions stay out of the record. The box's journal gets a
worktree.loginevent with the worktree, the email and whether it worked; cookie values never reach a log, an event or an error. Abefore:worktree.logingate can refuse a login.
Safety
A kit runs its scripts on the boxes you apply it to, with your account's access. Shipyard never applies one silently: adding shows everything it does and every file, and applying is a separate step you choose projects for.
- You keep what you reviewed. The review shows a hash of everything the kit carries. Adding fetches the link again and keeps the kit only if it still has that hash; a source that changed in between is refused, so review it again. Applying from the review likewise goes ahead only while the kept kit has the hash you saw.
- A kit needs no repository trust. A kit is yours once you add it, so
its config applies without the
trust prompt a
repository's own
.berth/config.jsonneeds. updatefetches a newer version but doesn't apply it: runberth kit applyagain once you've looked (berth kit show).
On a box, kit files can only be written inside the kit's own folder, and
before:kit.install / before:kit.remove gates can
refuse them.
berth kit help lists every kit command; the CLI reference
has them too.