shipyarddocs
shipyarddocs

Reference

Files and environment

Where Shipyard keeps its state on the laptop and on boxes, and the variables it sets and reads.

Shipyard keeps two kinds of files:

  • State, which Shipyard writes: identities, trust stores, sockets, logs. It lives in the state directory: ~/Library/Application Support/berth on a Mac, ~/.config/berth (or $XDG_CONFIG_HOME/berth) on Linux. BERTH_HOME moves it; it must be an absolute path.
  • Things you write, by hand or through the app: hooks, flows, templates, themes, plugins, kits. They live in ~/.berth/; BERTH_USER_DIR moves it.

On the laptop

State, in <state>/client/:

FileWhat it holds
identity.pemThis laptop's key
boxes.jsonPaired boxes, their addresses, fingerprints and networks
forwards.json, routes.jsonSaved forwards and routes
box-routes.jsonThe routes to each box besides its paired address (an SSH host, other addresses), and the ones turned off
ssh/The SSH routes' shared connections (ControlMaster sockets)
queue.jsonThe offline prompt queue
helpers.jsonThe plugins that are on with a helper, and the helpers still to be removed from a box that was offline when its plugin was turned off or removed. Gone when there is nothing to keep
agent.sock, agent.lock, agent.logThe laptop agent's socket, lock and log
ui-tokenThe token for the app's API (mode 0600)
linear.jsonYour Linear API key and who it belongs to (mode 0600); removed when you disconnect
networks/Embedded Tailscale nodes for other tailnets

Yours, in ~/.berth/:

FileWhat it holds
hooks.jsonLaptop hooks
templates/*.jsonTask templates
themes/*.jsonThemes
plugins/<id>/Plugins, each with a berth-plugin.json
plugins.jsonThe plugins you allowed, each with the hash of the code you reviewed (trust and consent)
plugin-sources.jsonThe plugins installed from the listing: the listing each came from, its version, and each file's checksum. A plugin not in it is one you put there yourself
.plugin-<id>-*/A plugin while it is being installed, replaced or removed; gone when that finishes
kits/<id>/Your kits library: kit.json, its files, and where it came from
app/<key>.jsonThe app's settings documents: saved prompts, projects, the sidebar, notifications

On a box

State, in <state>/box/:

FileWhat it holds
identity.pemThe box's key
clients.jsonPaired laptops (with a backup)
pairing.jsonPairing codes not yet used
listenThe address berthd serves on
berthd.sock, berthd.logThe local socket (mode 0600) and the log
locations.jsonLocations, each with the box's own config, its kit, and the hash of the repository config trusted there
ports.jsonEach worktree's block of ports
logs/Setup and archive logs
units/Unit and service logs
helpers/<plugin>/install.jsonA plugin's helper as it was installed: its name, version, arguments, size and SHA-256 (0600). berthd starts what this names, and checks the program against it each time
helpers/<plugin>/bin/<version>/<name>The helper's program, for its owner alone (0700). One version is kept
helpers/<plugin>/data/The helper's own data: {dir} in its arguments, and where it writes its ready file (with its token, if it asks for one). It stays when the helper is turned off, and goes when it is removed with its data
helpers/database/data/connections.jsonThe database editor's: the development databases of the worktrees it was told of, each URL with its password (0600). An entry goes when its worktree is detached
helpers/<plugin>/attached.jsonThe services that were last started with what the helper answered, so that turning it off can say which still point at it. It outlives the helper, and a removal with its data: a service leaves it when it is started again without the helper, or is found stopped when the helper is removed, and a worktree when it is removed. With nothing left in it, it goes, and the folder with it if nothing else is there
helpers/<plugin>/helper.log, helper.log.1What the helper printed, and when berthd started and stopped it (0600). Past 4 MB it starts over, and the log before that is kept once
kits/<location>/<kit>/Installed kits' files ($BERTH_KIT_DIR)
paused.jsonPaused worktrees
agent-states.jsonWhat each agent last reported, by working directory
tmux.confThe configuration of Shipyard's tmux server
commands/<session>.cmdEach session's command, prompt and all (0600), which its login shell runs; removed with the session
phone.jsonThe phone companion: on or off, its token, notifications
turncheck.key, turncheck-openai.keyThe AI Gateway and OpenAI keys pasted for turn check (0600)
runs/index.json, runs/<id>.jsonlRuns: the index, and each run's journal; finished runs past 100 per flow or template, or 30 days, are removed
runs/<id>.d/A run's headless agents' prompts and JSON output
flow-runs.json.importedFlow runs from before durable runs, once imported
autofix.jsonEach worktree's Auto-fix this PR settings
reviews.jsonReview settings: idle_days. Each review's mark (its PR, commit, author, and the keys it doesn't get) is in locations.json
browser/shots/<location>/<worktree>/Agents' browser screenshots, 20 per worktree
browser/viewports.jsonThe size an agent chose for each worktree's browser, by path; a worktree at the default 1920×1080 has none
browser/profiles/Running browsers' throwaway profiles, removed when each closes
browser-proxies.jsonEach worktree's browser proxy port
trigger-secrets.jsonWebhook flows' signing secrets (0600)
op-sessionThe 1Password CLI session berthd secret signin made (0600), passed to op for op:// reads; op ends it after 30 minutes unused
team/<id>/A team setup: what the laptop sent, its runner script, the progress file and its state
turns.json, turns-archive.jsonl, inbox.json, journal/, spool/The turn ledger, the event journal and hooks kept while berthd was down
flow-github.jsonWhat GitHub-triggered flows have already seen

Yours, in ~/.berth/: hooks.json, flows.json, env.json, guard.json, network.json, runs.json, plugins/ and plugins.json; see the config reference.

Sessions run in tmux on its own socket (tmux -L berth).

Environment

What a worktree gets

Everything run in a worktree (setup and archive scripts, terminals and agents, exec, repository hooks, flow steps, services):

VariableMeaning
BERTH_BOX, BERTH_LOCATIONWhere
BERTH_ROOT_PATHThe repository's main checkout
BERTH_WORKTREE_PATH, BERTH_WORKTREE_NAME, BERTH_BRANCHThis worktree
BERTH_WORKTREE_SLUGlocation_worktree, lowercase, safe for database names
BERTH_PORT, BERTH_PORT_1, …Its ports
BERTH_URLIts private URL as the laptop opens it: http://WT.LOC.BOX.localhost:1377
BERTH_BROWSER_PROXY, PLAYWRIGHT_MCP_PROXY_SERVER, PLAYWRIGHT_MCP_PROXY_BYPASSIts browser proxy
BERTH_KIT_DIRIts kit's files, when it has a kit
BERTH_REVIEW, BERTH_REVIEW_REPO, BERTH_REVIEW_SHA, BERTH_WITHHELDIn a review: the PR number, its repository, the commit checked out, and the names of the reviewer's own keys it does not get
thenthe box's env.json, the project's env, and resolved secrets (in a review, without the reviewer's own keys)
PORT$BERTH_PORT, for servers that read PORT, unless the box or env sets it
AGENT_BROWSER_IDLE_TIMEOUT_MSTerminals and agents: 300000, so an agent-browser left idle closes after 5 minutes, unless the box, env or berthd's environment sets it
ORCA_ROOT_PATH, ORCA_WORKTREE_PATH, ORCA_WORKSPACE_NAMESetup and archive scripts, for scripts written for Orca
what a helper answersServices only: before berthd starts one, each running plugin's helper that asks to be told may set the variables its manifest names (OTEL_*, a DATABASE_URL through its proxy). Each helper is shown the project's own values, not another helper's answer. Never a BERTH_ variable, and never one that names a secret

What a helper gets

A plugin's helper runs with a small environment of its own, not berthd's: what berthd itself was told (a token, a 1Password session) is not passed on.

VariableMeaning
PATH, HOME, USER, LOGNAME, SHELL, LANG, LC_ALL, LC_CTYPE, TMPDIR, TZberthd's own, where it has them
BERTH_HELPERThe plugin's id
BERTH_HELPER_DIRThe helper's data directory: {dir} in its arguments, and where it starts
BERTH_HELPER_HOMEThe box's helpers/ folder. With BERTH_HELPER it marks the process as a helper of this berthd's, which is how one left running by a berthd that was killed is found and ended
BERTH_BOXThe box's name

What a hook gets

See events and gates.

What Shipyard reads

VariableMeaning
BERTH_HOMEThe state directory
BERTH_USER_DIRInstead of ~/.berth
BERTH_ORIGINThe origin berth and berthd commands announce events with
BERTH_OPWhere the 1Password CLI is
OP_SERVICE_ACCOUNT_TOKEN, other OP_*Passed to op, from berthd's environment or env.json
SHELLThe shell scripts, sessions and exec run in
BERTH_PROXY_ADDR, BERTH_UI_ADDRberth agent only: where a second agent (a test, a throwaway home) listens instead of 1377 and 1378
BERTH_PLUGIN_REGISTRYberth agent only: the plugin listing to browse instead of https://berthd.app/plugins/index.json. An https:// link to an index.json; plain http:// only on localhost or 127.0.0.1
BERTH_CHROMIUMberthd: the Chromium for agents' browsers
BERTH_CLIA dev build of the desktop app (pnpm tauri dev): the berth to run for the laptop agent. The packaged app ignores it and runs only the copy it carries

The laptop agent explains what runs where; the config reference has the shape of every file you write.

On this page