Getting started
Install
One line puts berthd on a box. On your Mac, download the Shipyard app, which carries the berth CLI and updates itself.
Shipyard has two halves: berthd, the daemon on each box your agents run on,
and on your laptop the Shipyard app with the berth CLI inside it. The
release carries the app
for macOS, and berthd and berth for Linux and macOS, amd64 and arm64.
Formerly Berth
Shipyard was called Berth; its commands are still berth and berthd.
What you need
On the box (Linux, or macOS; amd64 or arm64):
gitandtmux(on a Mac,brew install tmux; on Debian or Ubuntu,sudo apt install tmux)curlorwget, andtar, for the installer- a Tailscale address, unless you tell berthd to listen elsewhere (see where berthd listens)
Before an agent starts, the app asks the box what it has. A box without
tmux, or without the agent's CLI, gets a card with the command that installs
it, typed out for you to run (on this Mac, Copy and open Terminal), and
Check again; nothing is created until it's there. berthd also finds a
Homebrew tmux (/opt/homebrew/bin, /usr/local/bin) when launchd starts it
without those on its PATH.
On your laptop: a Mac, Apple silicon or Intel. On an x86-64 Linux laptop, try the Linux app, an alpha, or use the CLI from the release. Building from source needs more; see build from source.
Put berthd on a box
On the box, as the user your agents will run as (it needs no root):
curl -fsSL https://berthd.app/install | sh==> Downloading berthd (latest, linux/amd64)
verified against checksums.txt
==> Checking this machine
service: /home/me/.config/systemd/user/berthd.service
listens on: 100.101.102.103:7444
==> Installing berthd v0.1.0 to /home/me/.local/bin/berthd
==> Starting the service
Installed /home/me/.config/systemd/user/berthd.service; berthd is serving on 100.101.102.103:7444.
Agent integrations (hooks for needs-you, working and done; Shipyard's skills):
Claude Code: skills in /home/me/.claude/skills; hooks added in /home/me/.claude/settings.json
Not found: Codex, Cursor Agent. After installing one, run: /home/me/.local/bin/berthd integrations install codex|cursor
berthd v0.1.0 is running. Paste this link into Shipyard on your laptop
(Add a box). It works once, for ten minutes:
berth://100.101.102.103:7444?code=…&fp=…
Or on your laptop: berth pair 'berth://100.101.102.103:7444?code=…&fp=…'
Your laptop will dial 100.101.102.103:7444. A new link any time: berthd pairIt downloads the latest berthd for the box's platform, checks it against
the release's checksums.txt, puts it in ~/.local/bin, and runs
berthd install. That sets berthd up as a user service (systemd on Linux,
launchd on macOS) and installs the hooks that report agents' state (needs
you, working, done) for the agent CLIs it finds on the box; --no-integrations
skips them, and first agent
covers one you install later. A box with no tailnet address gets a question
before berthd listens on every interface. The options, and running it again
to upgrade, are in add a box.
Keep the link it prints for pairing.
Rather not run anything on the box? Once the CLI is on your laptop,
berth add ssh me@my-box installs berthd over SSH and pairs in one step:
see over SSH.
Install the app
Download Shipyard for macOS, open the disk image, drag Shipyard to Applications, and open it. It's one app for Apple silicon and Intel Macs, signed with a Developer ID and notarized by Apple, so it opens like any other.
Or install it with Homebrew; this repository is its own tap:
brew tap cosscom/shipyard https://github.com/cosscom/shipyard
brew install --cask cosscom/shipyard/shipyardThe cask links berth into Homebrew's bin too, so there's no
command to install. The app still updates itself;
brew uninstall --cask shipyard removes the app and leaves your boxes,
pairings and agents alone; --zap also stops this Mac's laptop agent and
box and removes ~/.berth.
The app carries the berth CLI, the Linux builds of berthd that
berth add ssh and berth upgrade upload, and a berthd for the Mac itself
(Contents/Resources/berthd, signed and notarized with the app) for
Use this Mac, so there is nothing else
to install on the laptop. When the laptop agent
isn't running, the app offers to start it.
While no box is paired, it opens on a short setup that gets you to a running
agent in about a minute. Its first choice is Start on this Mac: Shipyard
installs the berthd it carries and pairs with it, with no terminal (see
this Mac); agents then run while the
Mac is awake, and you can add a server later. Then Use the sample makes
a tiny sample project (hello, a Node web server and its test, from
examples/hello)
in ~/work/hello, or add one of your own; and the composer opens with a
small first task written for the sample: press Enter and the first agent
starts in a worktree of its own. Connect a remote box, beside Start on
this Mac, adds a server instead (with the link the installer printed, over
your tailnet, or over SSH). With a box already paired, it opens straight to the main
window.
Updates
The app checks for a new release when it opens and every few hours after, and downloads it in the background. When one is ready, Restart to update shows in the status bar and in Settings → About; it never restarts by itself. Restarting the app doesn't stop your agents: they run on the boxes. The updated app restarts the Shipyard agent once it has finished what it's doing, so it runs the new version too, and this Mac's box is brought up to date; a note says Updated to vX.Y.Z. Settings → About → Check now checks straight away.
After an update with something new to try, a note at the foot of the sidebar opens What's new: the release's highlights one at a time, each with Show me to go there or the keys that do it. A new install doesn't get it. Settings → About → What's new, or "What's new" in ⌘K, opens it again.
The berth command
To use berth in a terminal, open Settings → General in the app and,
under Command line, click Install next to The berth command. It
asks first, then links ~/.local/bin/berth to the copy inside the app
(Shipyard.app/Contents/MacOS/berth-cli), so the command updates with the
app. If ~/.local/bin isn't on your PATH, add it
(export PATH="$HOME/.local/bin:$PATH" in your shell's profile); these
pages write berth. berth help lists every command.
Linux (alpha)
The Linux app is an alpha: x86-64 only, built on Ubuntu 22.04 with WebKitGTK, and less tested than the Mac app. Its sidebar and Settings → About say Alpha, and About has Report a Linux bug, which opens a GitHub issue; please paste Copy diagnostics into it.
-
AppImage (any distribution, updates itself): Shipyard for Linux (alpha), AppImage. Make it executable and run it:
mkdir -p ~/Applications curl -fL -o ~/Applications/Shipyard.AppImage https://github.com/cosscom/shipyard/releases/latest/download/Berth-linux-x86_64-alpha.AppImage chmod +x ~/Applications/Shipyard.AppImage ~/Applications/Shipyard.AppImageIt needs FUSE 2 (
libfuse2on Debian and Ubuntu,fuse2on Arch); without it, run it with--appimage-extract-and-run. The first launch registers it forberth://links. Updates replace the AppImage in place, so keep it somewhere you can write to. -
.deb (Debian, Ubuntu): Shipyard for Linux (alpha), .deb, then
sudo apt install ./Berth-linux-x86_64-alpha.deb. It installsberth-app(and the menu entry) and opensberth://links. A .deb install updates with a new .deb, not from inside the app.
Like the Mac app, it carries the berth CLI, the Linux berthd builds and
tmux, and a berthd for this computer. It copies them to
~/.local/share/berth/app/ on its first launch and after each update, and
runs the agent from there, because an AppImage's own files go away when it
quits; Settings → General → The berth command links ~/.local/bin/berth
to that copy. Start at login makes the agent a systemd user service
(berth-agent.service); without systemd's user session, the app starts the
agent on its own instead, and it runs until you log out.
What works differently, or not yet, on Linux:
- Keys. Ctrl stands in for ⌘, and the app shows its keys that way. In a terminal, Ctrl and a letter belong to the shell (Ctrl+W, Ctrl+D, Ctrl+K…): add Shift for the app's (Ctrl+Shift+T, Ctrl+Shift+K), and Ctrl+Shift+C and Ctrl+Shift+V copy and paste. There is no menu bar.
- Browser tabs show the page in a WebKitGTK view laid over the app, as the Mac app does with WebKit. Inspect opens WebKit's inspector docked inside the tab (its own button undocks it). The Console and Network drawer works as on the Mac.
- Title bar. Your window manager's, with no traffic lights; the window title ends in "(alpha)".
- Wayland. WebKitGTK runs natively on Wayland. With an NVIDIA GPU the
app turns off WebKit's DMA-BUF renderer, which leaves the window blank
there; if the window is still blank, try
WEBKIT_DISABLE_COMPOSITING_MODE=1. - arm64 has no build yet.
The CLI without the app
For the CLI alone, on Linux or a Mac, download it from the release:
mkdir -p ~/.local/bin
curl -fsSL "https://github.com/cosscom/shipyard/releases/latest/download/berth-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar -xz -C ~/.local/binThat fetches berth-linux-amd64.tar.gz on an x86-64 Linux machine (the
archive for each platform, and checksums.txt, are on the
release page). It
holds three files:
| File | What it is |
|---|---|
berth | The laptop CLI and background agent, for this computer |
berthd-linux-amd64, berthd-linux-arm64 | The box daemon for Linux boxes, which berth add ssh and berth upgrade upload |
Keep them together: berth add ssh and berth upgrade look for
berthd-<os>-<arch> beside their own executable.
Pair your laptop with the box
Paste the link the installer printed into the app (Add a box; pasting all of the output is fine), or:
berth pair 'berth://100.101.102.103:7444?code=…&fp=…'The link works once and expires after ten minutes; berthd pair on the box
prints a new one. From here on the laptop talks to the box over pinned
mutual TLS. More in add a box.
Start the laptop agent
The CLI and the app are clients of the laptop agent, a background process
that holds the connection to every box (see the laptop agent).
Any command that needs it starts it (berth boxes, for one). To have it
start at login and come back after a crash, install it as a service
(launchd on macOS, a systemd user unit on Linux):
berth agent install # berth agent status | uninstallIf the agent isn't running when the desktop app opens, the app offers to
start it: Start the Shipyard agent runs berth agent start, and ticking
Start at login first runs berth agent install instead. Nothing is
installed unless you tick it. The app runs only the copy of berth it
carries, and only while it is signed by the same team as the app (see
the security model). A dev build
(pnpm tauri dev) runs BERTH_CLI when set, then the repository's
bin/berth when there is one, and otherwise berth from ~/.local/bin,
/opt/homebrew/bin or /usr/local/bin. Without any of them, the app shows
the command to run in a terminal (berth status) and connects as soon as
the agent is up.
Optional: shorter URLs
Every port on a box has a private URL like http://3000.my-box.localhost:1377/.
On a Mac, you can drop the :1377:
berth setup port80 # asks for your admin password once; --remove undoes itIt redirects port 80 to 1377 on this computer. On Linux, grant the agent
CAP_NET_BIND_SERVICE instead.
Check everything
berth doctor # this computer: the agent, URLs, networks, boxes, agent tools
berth doctor my-box # a box: git, tmux, cloudflared, agents, where it listensEach check that fails says how to fix it.
Build from source
For working on Shipyard, or a laptop the release doesn't cover. You need
Go 1.27 for berth and berthd, and Node 22, pnpm and Rust for
the desktop app.
git clone https://github.com/cosscom/shipyard
cd berthd
make allmake all puts four files in bin/:
| File | What it is |
|---|---|
bin/berth | The laptop CLI and background agent, for this computer |
bin/berthd | The box daemon, for this computer |
bin/berthd-linux-amd64, bin/berthd-linux-arm64 | The box daemon for Linux boxes |
Where these pages write berth, run bin/berth from the clone, or put
bin/ on your PATH. Then run the app from the clone:
cd app
pnpm install
pnpm tauri devIt runs the clone's bin/berth for the laptop agent, or the one in
~/.local/bin if you downloaded the CLI instead of building it, so with
the CLI from the release you can run the app without Go. make app-build
builds Shipyard.app and its disk image, with the CLI and the Linux daemons
inside, under app/src-tauri/target/release/bundle/.