Guides
The phone companion
Which agents need you across your boxes, and answering them, from your phone.
Shipyard has a small phone app: which agents need you, across your boxes, and answering them, from your phone.
Setting it up
-
Your phone runs the Tailscale app, signed in to the tailnet your boxes are on.
-
In Shipyard, Settings → Phone: turn on phone access for each box.
-
Scan the code with the phone's camera. One code pairs every online box that has phone access on (or use Copy link to open it on the phone). Add the page to your home screen (Share → Add to Home Screen) so it opens like an app.
A home screen app keeps its own storage, apart from the browser, so a box paired in the browser is not paired there. Open the home screen app and paste the link from Copy link into Or paste a pairing link on its Pair screen (or on Boxes, to add one later).
For notifications, install ntfy on the phone, make a topic in Settings → Phone (New topic, then Turn on notifications), and subscribe to the same topic in the ntfy app. Boxes then push "Claude Code needs you · shop/checkout on devl" when an agent waits for you (and, if you switch it on, when one finishes its turn), and tapping it opens that agent in the phone app.
How it works
Each box serves the phone app itself, on its tailnet address, port 1379. Boxes are always on, so the phone works while your laptop is asleep or shut, which is when you want it. The page you pair with reads every box you paired, so one list covers all of them.
The phone can:
- list sessions and their agents' states (needs you, working, done, ready);
- read a session's screen;
- type a prompt into a session;
- press Enter, Esc, Ctrl-C, the up and down arrows, Tab, the digits 1–9, and y/n, which is what answering an agent's question takes;
- list the box's runs, see a run's steps in outline, approve or reject the gate one waits at (or pick the winning attempt), and cancel one. It cannot start runs. A run waiting at a gate is a "needs you" notification too, with ntfy when that is on, and the push opens the run.
For the Shipyard phone app, the box also offers (the phone API's version 2):
- an agent's recent conversation, as its chat shows it: prompts, replies, one-line tool calls, the files it edited with their line counts, its questions and their answers. Never tool output, thinking, file contents, diffs or older pages;
- what happens as it happens: which session or run changed, by name, so the app updates without asking every few seconds;
- notifications without ntfy, sent through Shipyard's push relay (below);
- stopping an agent, the way Stop does in the desktop app.
It cannot reach anything else on the box: not worktrees, locations, sessions' commands, hooks, flows, kits, shares, upgrades, or the box's own API. Those are different routes on a different port, and the phone listener does not serve them.
Notifications through the push relay
The Shipyard phone app asks each box it pairs with to notify it. Apple and
Google deliver a notification only from a server holding the app's own key,
which a box can't have, so the box asks Shipyard's push relay
(push.berthd.app) to send it:
- The app gets a device token from the phone and gives it to the relay, which seals it in a key only the relay can open.
- The app gives that key to each box (
POST /phone/v1/push). A box never sees the device token. - When an agent needs you, the box sends the relay the key and the notice: "Claude Code needs you", "shop/checkout on devl", and which session or run it is. The relay makes the notification from those few fields itself and keeps nothing.
The relay sees your box's name, the project and worktree, and the session or run's name, never what an agent wrote. Settings → Phone lists the phones each box notifies, and removes one. A new code, or turning phone access off, forgets them all. If the relay says a phone no longer takes notifications (the app was deleted), the box forgets it too.
Threat model
- Off by default. A box serves nothing for phones until a paired laptop turns it on, over the box's authenticated (pinned mutual TLS) API.
- Tailnet only. The listener binds the box's tailnet address, never every interface, and berthd refuses to start it on a box without one. Tailnet traffic is encrypted end to end by WireGuard, so the app is plain HTTP inside it.
- A token per box. 48 hex characters from the OS random source, kept in the box's state directory and shown only to paired laptops, as the QR code (or a link to copy). The phone stores it in its browser storage for that page. Pairing puts it in the URL's fragment, which browsers never send to a server, and the page removes it from the address bar at once. New code in Settings replaces it, and every phone paired with the old one stops working.
- Wrong tokens lock out. Ten wrong tokens in a minute from one address answer 429 until the minute is up.
- Host check. Requests must name the box by its tailnet address, a
*.ts.netMagicDNS name, or its own hostname, so a website cannot rebind a name it controls to the box's address and talk to it. - Cross-origin reads only from your tailnet. CORS allows pages served
from tailnet addresses and
*.ts.net(your other boxes' phone apps), with the token in a header, never a cookie. The app's page denies framing and only loads its own scripts. - What a stolen token allows. Anyone on your tailnet with a box's token
can read its agents' screens and recent conversations, follow which
sessions change, and type into its sessions, which is enough to instruct
an agent. They can also have the box notify a phone of theirs. Treat the code like a password: make a new one if a
phone is lost, and turn phone access off on boxes you don't need it on.
before:session.sendhooks see phone prompts, key presses and stops (from: "phone", withkeyfor a key) and can refuse them, andbefore:phone.pushhooks see a phone asking for notifications. - The conversation is a copy, field by field. The phone reads a conversation through its own route, which copies each field it may show from the box's reading, so a field added to the box's chat reaches a phone only when it is added there on purpose. Tool call ids, the agent's mode, model and tasks, published pages and the record's own name stay on the box. A command's output is cut to 2 KB.
- Events are rebuilt, not passed on. The phone hears agents', sessions' and runs' changes, by name and state, and a conversation that grew. Never paths, logins, secrets, hooks or any other event, and at most the last 500 when it catches up. At most 16 streams are open on a box; a new code closes every one.
- Notifications carry which worktree and box need you, never what the
agent wrote. An ntfy topic is readable by anyone who knows its name, so
the topic Shipyard makes is long and random; use your own ntfy server for
more. Pushes go to public addresses and your tailnet (
100.64.0.0/10), so a self-hosted ntfy on the tailnet works as it is. One on your LAN, on the box itself, or anywhere else private must be allowed in the box's~/.berth/network.json(see outbound requests); the check is made on the address actually dialled, redirects included. - The push relay is chosen by a paired laptop, never by a phone, and the box reaches it on public addresses only. It gets the same notice ntfy does, plus the key that names the phone, and keeps neither.
What works where
| iOS (Safari, home screen) | Android (Chrome) | |
|---|---|---|
| The app over the tailnet | Yes | Yes |
| Add to home screen | Yes, opens full screen | Yes |
| Notifications through ntfy | Yes, with the ntfy app | Yes, with the ntfy app |
| Web Push straight from a box | No | No |
| Notifications through the push relay | The Shipyard app | The Shipyard app, later |
Web Push needs a secure context (HTTPS) for the service worker it relies on,
and a tailnet address over HTTP is not one. Serving the app over HTTPS would
take a certificate for each box's *.ts.net name (tailscale cert), which
is the next step if notifications without ntfy are wanted.
For how the phone fits Shipyard's security as a whole, see security.
Agent integrations
Claude Code, Codex, Cursor, Gemini CLI, OpenCode and oh-my-pi hooks, the skills Shipyard teaches agents, and announcing events from any tool.
More than one computer
Use Shipyard on a second computer, a Mac mini beside your MacBook say, with the same boxes. Both stay paired and work at once.