shipyarddocs
shipyarddocs

Concepts

The laptop agent

The background process that holds every box connection, serves private URLs, and outlives the app.

The Shipyard agent (berth agent) runs on your laptop in the background. It holds a connection to every paired box, runs saved forwards and the *.localhost proxy, and serves a local API that the CLI and the desktop app are clients of. Closing the app, or the app crashing, never stops a session, a forward or a queued prompt.

What it does

  • keeps one pinned TLS connection per box, reconnecting forever, with health pings to notice a connection that died silently and sleep detection. A box whose check is slow or gets no answer is marked slow and checked again in about 2 seconds; only a second failure in a row (or a refused connection, a wrong key, or the box saying it is stopping) takes it away, and away it is tried again after about 2 seconds, then 4 and every 8, each give or take 20% so boxes don't all retry at once. A request that waits 10 seconds for an answer has the box checked at once, and a request for a box known to be away is answered straight away instead of waiting out a dial (Slow and dropping networks);
  • serves private URLs on port 1377, http://3000.devl.localhost:1377/, and runs forwards (a fixed local port to a box port) and routes; a box's URLs work by the name you paired it as and by the box's own name (see below);
  • relays every online box's events, so laptop hooks, plugins and the app hear about every agent on every box;
  • runs laptop hooks from ~/.berth/hooks.json;
  • holds the offline prompt queue and delivers it when boxes come back;
  • runs an embedded Tailscale node for each other tailnet;
  • keeps your kits library and serves your themes, task templates and plugins to the app.

A box's own name

You name a box when you pair it (devl), and the box has a name of its own (devbox, its hostname's first label, so devbox.europe-north1-a.c.example.internal is devbox too). URLs the box makes, such as $BERTH_URL or an app's configured origin, use its own name: http://checkout.shop.devbox.localhost:1377. The proxy accepts both, so a link an agent prints opens on your laptop, and on a new computer that paired the box under another name. It learns each box's own name when the box comes online, and skips a name that is also one of your paired boxes or that two boxes share. The app's browser tabs show either by your name for the box.

A server's redirect to its own localhost:PORT goes back to the address you opened, and one to another port on the box's loopback (an auth server on localhost:4000) goes to that port's name, http://4000.devl.localhost:1377, since localhost there means the box, not your laptop.

Running it

Any command that needs the agent starts it, and when the desktop app finds it isn't running, it offers to: Start the Shipyard agent runs berth agent start, and ticking Start at login installs it as a service instead. To have it start at login and restart after a crash from a terminal:

berth agent install      # launchd on macOS, a systemd user unit on Linux
berth agent status
berth agent uninstall
berth agent              # run it in the foreground instead
berth agent restart      # restart it once its work under way is done
berth stop               # stop it, and every forward

The agent outlives the app, so an update to Shipyard would leave it running the old version. The updated app restarts it as it starts (berth agent restart --if-stale), whether the app started it or it starts at login: the agent first finishes what it's doing (adding or upgrading a box, setting up this Mac's box, sending a queued prompt), and agents' sessions keep running on their boxes throughout. The new agent then brings this Mac's box up to date.

berth status             # boxes, forwards and the proxy at a glance
berth events             # every event from this laptop and every box, live
berth doctor             # what's wrong on this computer, and how to fix it

How things reach it

ClientHow
The CLIA Unix socket, agent.sock, in the state directory
The desktop app and pluginshttp://127.0.0.1:1378 with a bearer token; see the app's API
Your browserhttp://*.localhost:1377/, the proxy

Where it keeps things

State is in ~/Library/Application Support/berth/client/ on a Mac and ~/.config/berth/client/ on Linux ($BERTH_HOME moves it): its identity, paired boxes, forwards, routes, the queue, logs and the app's token. Things you write by hand are in ~/.berth/ ($BERTH_USER_DIR moves it): hooks, task templates, themes, plugins, kits. The full list is in files and environment.

Next: the security model, how the agent and your boxes trust each other.

Routes to a box

A box can be reachable more than one way: over Tailscale, which may relay it through a server on another continent when both networks are strict; over SSH, which often goes direct; or at an address on your LAN. The agent knows each route to a box and sends new requests over the fastest one that works.

  • Where routes come from. The address the box was paired at is one. A box added with berth add ssh also gets an SSH route to the host it was added with, on by default. A host in your ~/.ssh/config with the box's own name is offered, off. You can add an SSH host or an address, and turn any route off, in Settings › Boxes › Routes.
  • SSH routes use your ssh. The agent runs ssh -W to berthd's port with your ~/.ssh/config, agent and keys (1Password's agent included), as ssh HOST would in a terminal. It never reads, stores or asks for a key, and never edits your SSH config: ssh runs in batch mode, so a login that would need you (a password, an unknown host key) fails instead, and the route shows as down. One login is shared by the route's connections.
  • Every route is only a transport. The same TLS, pinned to the key the box was paired with, runs on every route. A route that reaches anything else is refused, as the paired address would be.
  • Measuring. While you use a box, each route not carrying its traffic is measured every 30 to 45 seconds; a box you aren't using isn't. A route clearly faster than the one in use (a quarter quicker) takes over.
  • Failing over. The agent checks each box every 10 seconds, and at once when a request is slow to answer or typing gets no echo. If the route in use doesn't answer within 3 seconds, the others are asked, and the first to answer carries new requests from then on. Open terminals and the event stream stay on the old route in case it was a hiccup; if it fails again (about 5 seconds later), it is down, and they move to the new route: a terminal attaches again inside the same tab, the box redraws it, and keys that may not have reached the box are sent again. A route that comes back is used again if it is the faster one.

berth boxes shows the route each box is reached by, and berth doctor BOX lists them all with their latency.

Slow and dropping networks

Boxes are often far away (100–900 ms over Tailscale), and links drop. A link through one of Tailscale's relays can sit at 80 ms and then spike to 2 seconds. Shipyard rides that out rather than calling the box offline:

  • Slow, not offline. A health check (every 10 seconds) that takes over 1.5 seconds, or gets no answer in 8, marks the box slow: the status bar says 1/1 box online · slow, the sidebar lists the box with "slow", and Settings › Boxes says why ("health check took 1.9s") with its latency. Requests to a slow box still go through, and its connection is kept, so terminals and chats on it carry on. It is checked again about 2 seconds later, with 10 seconds to answer; one good check makes it online again.

  • Away takes two failed checks in a row, so a box that really went shows Reconnecting about 20 seconds after it stopped answering (8 s, 2 s, then 10 s). A refused connection, a key other than the box's pairing's, or the box saying it is stopping (berthd restarting) is away at the first check.

  • The agent's log (berth agent in a terminal, or its log file) has a line for every change, with why, and nothing for the checks in between:

    box cal: online → slow (health check took 6.2s)
    box cal: slow → away (2 checks failed: no answer in 10s)
    box cal: away → online (health check took 84ms)
    box cal: relayed through Tailscale's New York server: no direct connection (this computer's nearest is London)

What you see when a box does drop off:

  • Reconnecting to devl… Next try in 6s. A terminal, a chat and a team setup in progress say the box is away, count down to the agent's next try, and offer Try now. The session keeps running on the box; the terminal comes back as it was, and the chat and the setup catch up from the box's events, which the agent asks for from the last one it saw.
  • Waiting for devl to answer… Typing in a terminal that gets nothing back for 4 seconds says so (what you type may not arrive while the link is down), and has the agent check the box now.
  • devl isn't answering. A read that has no answer in 30 seconds (⌘P, the Files panel, a diff) fails with that, rather than spinning, and asks you to try again in a moment.
  • A message sent again after the link dropped its answer carries the same idempotency key, so the box types it once.
  • The app's own connection to the agent (its event stream) is dropped and opened again if it is silent for 45 seconds, as after the laptop sleeps, with a jittered backoff, and refetches what changed; refreshes that land together run as one.

Tailscale connects two machines directly when it can. When it can't, it carries their traffic through one of its relay (DERP) servers, which works anywhere but adds the trip to that server and back, and slows down when the server is busy. The relay used is the box's nearest, which can be on another continent from you. Settings › Boxes says when this happens:

Relayed through Tailscale's New York server: no direct connection (this computer's nearest is London)

berth doctor BOX says the same, under Link from this computer. For a box on this computer's own Tailscale, the agent asks tailscale status (read only, at most every two minutes); for a box on one of its own networks, it asks that network.

Why it happens: both ends are behind NAT that Tailscale can't get through (a "hard" NAT, where the port changes with every destination, often on phone hotspots, corporate networks and some home routers), or UDP is blocked on the way. A VM at a cloud or hosting provider is usually behind the provider's NAT too. You can check with tailscale netcheck on each end: MappingVariesByDestIP: true is a hard NAT.

What fixes it, best first:

  • Let UDP 41641 in to the box. Tailscale's direct connections use UDP port 41641. Open it inbound in the box's cloud firewall or security group, and the two ends can meet directly even when your end is behind a hard NAT.
  • A VM behind its host's NAT needs a port forward there: forward UDP 41641 on the host (or the provider's NAT, router or load balancer) to the VM. ufw on the VM is often inactive and is rarely the blocker; check with sudo ufw status before changing it.
  • Another route. If SSH to the box goes direct (it often does, as SSH doesn't need the NAT traversal Tailscale's direct connections do), an SSH route carries Shipyard's traffic instead while it is the faster one. A box added with berth add ssh has one already; add one in Settings › Boxes › Routes.
  • A nearer relay, or a peer relay. If a direct connection isn't possible, a Tailscale peer relay on a machine with an open UDP port near you both, or a custom DERP server nearer than the one in use, cuts the detour.

Run tailscale ping BOX after a change: it says via DERP(nyc) while relayed and an IP address and port once it is direct. The note in Settings › Boxes goes within a couple of minutes.

On this page