shipyarddocs
shipyarddocs

Reference

Config reference

Every field of .berth/config.json, kit.json, and the box's own config files.

.berth/config.json

A repository's config, committed at .berth/config.json. The same shape is a kit's config and a box's own config for a location. A missing file means no config; a file that doesn't parse is an error the app and CLI show. A guide is in project config.

FieldTypeMeaning
setupstringRun in a new worktree, through a login shell, after it is created. Up to 30 minutes, logged on the box.
archivestringRun before a worktree is removed, after its services stop. If it fails, the worktree stays.
portsnumberHow many ports each worktree gets, 0 to 10. Every worktree gets at least one.
envobjectVariables for everything run in a worktree. Keys are [A-Za-z_][A-Za-z0-9_]*. Values can use $NAME for BERTH_* variables and berthd's environment, or be a secret reference.
servicesarrayServices run in every worktree.
agentsarrayAgent presets to add, or to replace built-ins by id.
hooksarrayHooks for this repository's events only, run in the worktree.
flowsarrayFlows for this repository's worktrees.
shotsobjectWhat berthd shots compare shoots and diffs by default. Read from the worktree's own file, trusted or not: it names pages and selectors and runs nothing.
loginobjectDev users a worktree can be logged in as, and the script that logs one in.
review_buttonbooleanAdd a Review in Shipyard button to the description of each PR opened from the project's worktrees. Off by default; from the repository's file it applies once the box trusts it.
keep_mainbooleanKeep the default branch current: before a new branch is made from it, fetch it and fast-forward the local one, never past uncommitted changes or local commits (how). On by default; false turns it off.

services

FieldTypeMeaning
namestringRequired. [a-z0-9][a-z0-9-]*, at most 32 characters, unique.
runstringRequired. Run in the worktree through a login shell, with its environment and PORT.
autostartbooleanStart when the worktree is created, after setup succeeds.
terminalbooleanRun in a terminal of its own, shown as a tab in the worktree, instead of in the background. Ctrl-C there stops it. Needs a box with the service.terminal capability. See services in a terminal.
titlestringThe tab's name, one line of at most 48 characters. Default: name.

agents

FieldTypeMeaning
idstringThe preset's id. The same id as a built-in (claude, codex, opencode, gemini, cursor) replaces it.
namestringShown in the app.
commandstringWhat to run.
prompt_flagstringHow the agent takes a first prompt, when it needs a flag (--prompt). Empty: the prompt is the last argument.
acpstringWhat follows command to start the agent's Agent Client Protocol server (acp, --acp). With it the agent can run in chat. Given with an id and no command, it adds that to a built-in agent.

The built-ins are offered when their command is installed on the box: claude, codex, opencode (--prompt), gemini (-i), omp (oh-my-pi) and cursor (cursor-agent).

hooks

FieldTypeMeaning
onstringRequired. An event type, a prefix like worktree.*, *, or before: and an action for a gate.
runstringRequired. Run through /bin/sh -c with the event on stdin and in BERTH_* variables.
timeoutstringA Go duration. Default 1m, or 30s for gates.
toolstringNever run for events whose origin is this tool.

The same shape is used in ~/.berth/hooks.json ({"hooks": [...]}) and in a plugin's manifest. See hooks.

flows

FieldTypeMeaning
idstringRequired. [a-z0-9][a-z0-9-]*, at most 48 characters, unique.
namestringRequired.
enabledbooleanDefault false: a flow runs only when it is true.
triggerobjectExactly one of event, schedule, github or webhook; see below.
stepsarrayAt least one; see below.
max_runs_per_hournumberDefault 20 when empty or 0.
queuenumberTriggers that may wait behind the flow's run in the same worktree (default 5, at most 50); past it, a trigger is refused and a GitHub item tried again on the next look.
coalescebooleanNew GitHub items merge into the run already waiting, as {{event.items}}, instead of queueing their own.

trigger

FieldTypeMeaning
eventstringAn event type or prefix. Not a before: gate.
schedulestringCron (m h dom mon dow) or @hourly, @daily, @midnight, @weekly, @monthly, @yearly, @annually; the box's local time.
each_worktreebooleanWith schedule only: once for every worktree.
githubobjecton: review_comment, pr_review, check_failed, pr_merged, issue_labeled (with label) or issue_assigned (with assignee, default @me); poll: a duration, at least 1m, default 2m.
webhookobjectStarted by a signed POST /v1/triggers/<id>; branch_field names the posted field that picks the worktree (default branch).
whereobjectlocation, agent, branch (a trailing * matches a prefix), and for GitHub triggers author (logins, "collaborators" or "*"; review_comment and pr_review default to collaborators). Empty matches anything.

steps

Each step:

FieldTypeMeaning
idstringOptional, unique in the flow. Unnamed steps are 1, 2, …
kindstringrun, prompt, wait, start_agent, notify or webhook, or a run step: check, loop, map, join, if, gate, sleep, judge, headless, collect, handoff, pr, cleanup.
whenstringsuccess (default), failure or always.
commandstringrun: required. Variables reach it as environment variables, never as code.
textstringprompt: required, the prompt. start_agent: its first prompt. notify: the body. webhook: the JSON body (default: every variable).
titlestringnotify: required.
sessionstringprompt: which session (default: the event's session, else the agent running in the event's worktree, else one an earlier step started).
forarraywait: states that end it (default finished, waiting).
agentstringstart_agent: required, a preset id.
new_worktree, nameboolean, stringstart_agent: in a new worktree, and its name.
urlstringwebhook: required, http or https; public addresses only unless allowed.
timeoutstringA duration: run 10m, check 20m, wait 30m, webhook 15s by default; at most 2h.
deliverstringprompt: idle holds it on the box until the agent is idle.
max, until, stepsnumber, string, arrayloop: rounds (default 3, at most 50), a condition that ends it, and its steps.
items, concurrency, modelist or text, number, stringmap: what to fan out over (a list, or text whose lines are the items, {{item}} and {{item.FIELD}} in its steps), how many at once, and all, any or first_success.
cond, elsestring, arrayif: a condition, and the steps when it is false.
on_timeoutstringgate: reject (default), approve or fail.
durationstringsleep: how long, kept across restarts.

Variables and behaviour are in automations.

shots

Defaults for visual diffs. Flags on berthd shots compare override them for one run (--mask adds to mask).

FieldTypeMeaning
pagesarrayPaths to shoot, such as ["/", "/login"]. Default ["/"]; at most 50.
sizesarrayViewport widths in CSS pixels, 240 to 2560, at most 6. Default [375, 768, 1280] (shot at 812, 1024 and 800 pixels high).
maskarrayCSS selectors of dynamic content (clocks, avatars, relative dates), painted flat on both sides and left out of the diff.
thresholdnumberThe colour distance, 0 to 1, under which two pixels count as the same. Default 0.03.
unchanged_belownumberThe share of changed pixels, in percent, under which a shot counts as unchanged. Default 0.02.
max_heightnumberFull-page shots stop here, in CSS pixels. Default 4000.
scalenumberDevice pixel ratio, up to 3. Default 1.
color_schemestringlight (default), dark, or both (every shot in each).
wait_forstringA selector every page must show before its shot (up to 10 seconds).
seed_randombooleanMath.random repeats the same numbers on every load.
parallelnumberBrowser tabs shooting at once. Default: the box's CPUs, from 2 to 8.

login

FieldTypeMeaning
scriptstringRequired. A path inside the config's folder: the kit's own folder for a kit, the main checkout's .berth/ for the repository's file and the box's own config. No .., no absolute path; a symlink that leads outside is refused when it runs. Run in the worktree, with its environment and BERTH_LOGIN_EMAIL, for up to 30 seconds.
usersarrayEmails, or { "email", "label" }, at most 50. An email is a plain address: letters, digits and . _ + - before the @, starting with a letter or digit, at most 254 characters. A label is one line of at most 48 characters, shown in place of the email.
anybooleanAny valid email may log in, not only users. Default false.

The script prints one JSON object on stdout, at most 64 KB: {"cookies": [{"name", "value", "path"?, "httpOnly"?, "secure"?, "sameSite"?, "maxAge"?}], "redirect"?: "/path"}. One to 32 cookies; no domain (a cookie is set for the worktree's own address); sameSite is Lax, Strict or None; maxAge is 1 second to 400 days; redirect is a path on the worktree. Anything else, a non-zero exit or a timeout is an error that never quotes the output. A login comes from the kit, the box's own config, or the repository's trusted file in the main checkout, never from a worktree's own checkout. See personas.

How layers merge

A location's effective config is the repository's file, then its kit's config, then the box's own config for it:

FieldMerge
setup, archiveThe later one wins if set
portsThe later one wins if set
envKey by key; the later one wins
services, agents, flowsBy name or id: a later one replaces, new ones are added
hooksAdded up: the file's, the kit's, then the box's
loginWhole: the later one's script and users replace the earlier one's
review_buttonThe later one wins if set (false too); with none set, the team's team.json decides
keep_mainThe later one wins if set (false too)

Only the effective flows run: a flow replaced by id never does, and a replacement with enabled: false switches the flow off on that box. GET /v1/flows lists every layer's flows, with overridden: true on the replaced ones.

The repository's file counts only once it is trusted on the box, for its exact content (its SHA-256 hash); until then, and again after any change to it, only its ports apply and GET /v1/locations/{name}/config reports repo_trust: {state: "untrusted" | "changed", hash, wants}, with wants holding the whole file. A file that runs nothing (only ports, say) needs no trust. Trusting and untrusting run before:config.change gates and announce config.changed. See trusting a repository's config.

berth location config BOX/LOC prints the effective config, and what an untrusted file would run with its hash; --json shows each layer (repo, kit, local, effective, repo_trust). --trust HASH trusts the file as shown, --untrust stops running it.

kit.json

FieldTypeMeaning
idstringRequired. [a-z0-9][a-z0-9-]*, at most 48 characters.
namestringDefault: the id.
descriptionstring
versionstringShown. A project is flagged as running an older kit when its installed contents (their hash) differ from the kit on this laptop.
matchobjectslug: the owner/repo it is for. Selects matching projects in the app; nothing enforces it.
requiresarray{ "tool": "psql", "hint": "how to install it" }. A missing tool is a warning when the kit is applied.
configobjectA .berth/config.json, validated by the same rules.
loginobjectThe same as config.login, at the top for short kits; set one or the other.
filesobjectSmall files inline, { "scripts/setup.sh": "…" }. Paths stay inside the kit.
watcharrayThe repository's files that change how the kit sets a worktree up, as globs (* within a folder, ** any folders): ["prisma/**", "scripts/setup/*"]. A pull request that changes one says so on its review sheet.

A kit's files are copied to each box it is applied to, and $BERTH_KIT_DIR points at them. Files starting with #! are made executable. See kits.

Task templates

~/.berth/templates/<id>.json on the laptop:

FieldTypeMeaning
idstringDefault: the file's name without .json.
namestringShown in the composer's Template picker (⌘N → Options).
descriptionstring
agentstringA preset id.
commandstringRun instead of the agent preset; the template's prompt is then not passed.
branch, basestringThe branch (with {{name}} and variables) and what it starts from.
promptstringThe first prompt, with variables.
variablesarray{ "id", "label", "default", "multiline" } for each {{var}}.

See task templates.

Box files

In ~/.berth/ on a box:

FileShapeWhat it is for
hooks.json{ "hooks": [Hook] }Hooks for the box
flows.json{ "flows": [Flow] }Flows for any project on the box
env.json{ "env": { "KEY": "value" } }Environment for every worktree on the box, under each project's own; values may be secret references. OP_* keys reach op.
guard.json{ "enabled", "memory_percent", "sustain", "stop_services", "pause_agents" }The resource guard
turncheck.json{ "enabled", "provider", "key", "url"?, "model"? }Turn check: off by default. provider is gateway, openai or laya, with no default; key is a secret reference to that provider's key (op://… or env://NAME), never the key; a key pasted in Settings is kept in the state directory instead (files). model is the model that checks turns, with no default; url is a Laya server of your own, which never gets a key. Set from Settings → Agents, on a paired laptop
network.json{ "allow_outbound": ["10.0.0.0/8", "192.168.1.20", "ntfy.home.lan"] }Private addresses flow webhooks and phone notifications may reach: IP addresses, CIDR prefixes or host names (outbound requests). Nothing in the API changes it
plugins/<id>/berth-plugin.jsonA plugin manifestIts hooks run on the box too, once allowed in plugins.json
plugins.json{ "plugins": { "<id>": { "hash"? } } }The plugins whose hooks may run on the box; an entry without a hash trusts whatever the folder holds (trust and consent)

Changing env, flows, the guard or a location's config through the API runs before:config.change gates and announces config.changed. Where every file lives is in files and environment.

On this page