shipyarddocs
shipyarddocs

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 laptop

In 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.

Kits: Shop development v3, for acme/shop, from acme/kits, with setup and teardown, 2 env vars, 2 services, an automation, a hook and 3 files, applied to shop on devl at an older version with Update 1 project; and Node app v1 from the hello-ports plugin, not applied yetKits: Shop development v3, for acme/shop, from acme/kits, with setup and teardown, 2 env vars, 2 services, an automation, a hook and 3 files, applied to shop on devl at an older version with Update 1 project; and Node app v1 from the hello-ports plugin, not applied yet

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, or URL#shop-dev, with @ref for 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
kit.json
{
  "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.

A worktree's tab with two panes: the Next.js service's terminal, showing next dev starting and serving requests, and a browser pane with the page it serves, an order summaryA worktree's tab with two panes: the Next.js service's terminal, showing next dev starting and serving requests, and a browser pane with the page it serves, an order summary

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:

kit.json
{
  "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
    }
  }
}
  • script is 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, its DATABASE_URL…) and BERTH_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.
  • users are emails, or { "email", "label" }. People see the label.
  • any: true lets a link or a command name any valid email, not only the listed ones. It is false unless 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):

scripts/login.sh
#!/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 to next.
  • An agent: berthd browser open --as pro@acme.test --path /orders logs the agent browser in the same way.
  • A review link: berth://review?repo=acme/shop&pr=42&as=pro@acme.test&path=/orders opens 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.test logs 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.json in 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/login route takes GET from your own laptop, and only when nothing else started it: a request another site or another worktree's page sent (by its Origin, its Referer, or Sec-Fetch-Site) is refused. It is the laptop's own: it never reaches the dev server.
  • next stays 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": false so is an email the config doesn't list.
  • Sessions stay out of the record. The box's journal gets a worktree.login event with the worktree, the email and whether it worked; cookie values never reach a log, an event or an error. A before:worktree.login gate 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.json needs.
  • update fetches a newer version but doesn't apply it: run berth kit apply again 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.

On this page