Guides
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.
Every computer you use Shipyard on pairs with your boxes with its own key. To set up another one, the computer you already use makes a join link: one fresh, single-use pairing code from each box, in one link. The new computer pairs with every box in it. Nothing changes for the first computer; both work at once, and each box lists both.
Adding a computer
On the computer you already use:
- Settings → Computers → Add another computer.
- Choose the boxes (online ones are ticked; an offline box can't make a code until it's back).
- Read what the link gives away, then Make the link. You get the link, a QR code of it, and how long it lasts.
On the new computer, install Shipyard, and on the welcome screen choose I already use Shipyard on another computer. Paste the link (the whole message is fine), check the boxes it lists, and Pair. Its projects are already on the boxes, so setup ends there.
A computer that already has boxes joins from Settings → Computers → Use a join link.
The QR code is the same link, for a phone's camera to copy across (on Apple devices, Universal Clipboard pastes it on the Mac).
From a terminal
# On the computer you use now
berth invite # every paired box
berth invite --boxes devl,build # only these
# On the new one
berth join 'berth://join?v=1&d=…'
berth join --check '…' # what the link holds, without pairingberth invite asks before it makes the link; --yes doesn't. berth join -
reads the link from stdin.
Boxes on another tailnet
A box the first computer reaches through a Shipyard network
(another tailnet) carries that network's name and tailnet in the link. The
new computer reaches it through a network of its own by that name when it
has one, and otherwise directly, which works when its own Tailscale is on
that tailnet. When neither does, the box waits with Sign in: sign in to
that tailnet in the browser, and Shipyard pairs with it then. In a terminal,
berth join offers the same sign-in.
Who can reach a box
Settings → Computers lists, for each online box, the computers it trusts:
their names (from each computer's hostname), key fingerprints and when they
paired, with This computer marking yours. Remove… stops a box trusting
another computer at once: its terminals, forwards and event streams on that
box close, and the agents keep running. A computer can't remove itself here;
Forget the box in Settings → Boxes instead. On the box, berthd clients
and berthd revoke do the same.
What the link is, and isn't
The link is as powerful as the boxes in it: whoever pairs with it can run commands, read code and open terminals there. Share it only with yourself.
- Single use, ten minutes. Each box's code is the same as one
berthd pairprints: it works once and expires after ten minutes. A second computer using the same link is refused by every box. - Never sent. The new computer proves it holds each code over its own TLS session (see pairing); the code itself never crosses the network, and no box logs it or puts it in an event.
- Pinned. The link carries each box's key fingerprint, and the new computer refuses a box that presents any other key, so a changed address or fingerprint pairs with nothing, and leaves the real code unused.
- Nothing else. It holds the boxes' names, addresses and fingerprints, the codes, and the inviting computer's name. Never that computer's key, its app token, or any settings.
- Asked for, and limited. Making a link asks first, in the app and in
the CLI. Each box makes at most ten codes per ten minutes, runs the
before:pairing.invitegate first, and announcespairing.invited(who asked; never the code). A new computer pairing announcesclient.paired; removing one,client.revoked.