shipyarddocs
shipyarddocs

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):

  • git and tmux (on a Mac, brew install tmux; on Debian or Ubuntu, sudo apt install tmux)
  • curl or wget, and tar, 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
Example output
==> 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 pair

It 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/shipyard

The 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.AppImage

    It needs FUSE 2 (libfuse2 on Debian and Ubuntu, fuse2 on Arch); without it, run it with --appimage-extract-and-run. The first launch registers it for berth:// 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 installs berth-app (and the menu entry) and opens berth:// 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/bin

That 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:

FileWhat it is
berthThe laptop CLI and background agent, for this computer
berthd-linux-amd64, berthd-linux-arm64The 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 | uninstall

If 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 it

It 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 listens

Each 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 all

make all puts four files in bin/:

FileWhat it is
bin/berthThe laptop CLI and background agent, for this computer
bin/berthdThe box daemon, for this computer
bin/berthd-linux-amd64, bin/berthd-linux-arm64The 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 dev

It 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/.

Next

Your first project and worktree, then your first agent.

On this page