shipyard README

The project's README from github.com/cosscom/shipyard. As one markdown file: README.md.

Berth

https://www.berthd.app/ Run coding agents on your dev boxes, and work with them as if they were on your laptop.

Berth connects a laptop to any number of development machines (a VPS, a cloud VM, a desktop under your desk) and gives each repository on them worktrees, terminals, agents, dev servers and automations. The agents run on the boxes, so closing the app, sleeping the laptop or losing Wi-Fi never stops them; the app is a view you can close and reopen at any time.

Pieces
berthd The daemon on each box: worktrees, sessions (tmux), services, hooks, flows, kits.
berth The laptop CLI and background agent: connections, private URLs, the app's API.
app/ The desktop app (Tauri, React, coss ui).
plugins/ Built-in plugins, written against packages/plugin-sdk.
kits/ Pointers to kits kept in their own repositories, such as the Cal.com kit.

Getting started

On each box, as the user your agents will run as:

curl -fsSL https://berthd.app/install | sh

It downloads berthd from the latest release, checks it against the release's checksums, installs it for that user (no root), starts it as a systemd user service (launchd on macOS), installs the hooks that let Claude Code, Codex and Cursor report their state (--no-integrations skips them), and prints a pairing link. The link works once, for ten minutes. Run it again to upgrade in place; sh -s -- --help lists the options.

On your Mac, download Berth (Berth-macos-universal.dmg, for Apple silicon and Intel, signed and notarized), drag it to Applications and open it. The app carries the berth CLI and the Linux daemons berth add ssh uploads, and offers to start the laptop agent when it isn't running. It updates itself: new releases download in the background, and Restart to update in the status bar or Settings → About applies one; it never restarts on its own, and restarting never stops an agent.

For berth in a terminal, Settings → General → Command line → Install links ~/.local/bin/berth to the app's copy (it asks first). On a Linux laptop, or for the CLI alone, download it from the release (use linux-arm64, darwin-arm64 or darwin-amd64 to match):

mkdir -p ~/.local/bin
curl -fsSL https://github.com/cosscom/shipyard/releases/latest/download/berth-linux-amd64.tar.gz | tar -xz -C ~/.local/bin

Paste the box's link into the app (Add a box), or:

berth pair 'berth://100.101.102.103:7444?code=…&fp=…'

Instead of the install line, berth add ssh can install and pair a box over SSH in one step. Then add a project and start an agent, in the app or here:

berth add ssh me@my-box                    # or: install on the box over SSH, and pair
berth location add my-box/app ~/work/app
berth task new my-box/app/fix-login --agent claude --prompt "Fix the login redirect"

berth help lists every command; every listing takes --json.

Build from source

With Go 1.27, Node 22, pnpm and Rust. make all builds berth and berthd into bin/; the app runs the clone's bin/berth for the laptop agent:

git clone https://github.com/cosscom/shipyard
cd berthd && make all
cd app && pnpm install && pnpm tauri dev

make app-build builds Berth.app and its disk image, with the CLI and the Linux daemons inside.

Docs

The documentation is at docs.berthd.app. Its pages are the docs/ folder here, built by docs-site/:

Development

make test               # go vet + go test -race
pnpm -C app build       # typecheck and build the app
pnpm -C docs-site dev   # the docs site, on http://localhost:3333

Licence

MIT.

shipyard (cosscom/shipyard)

systemd
Searching Database…

321 ·GitHub
Shipyard
What is this?Berth lets you run coding agents like Claude Code and Codex on remote dev boxes - a VPS, a cloud VM, or a desktop under your desk - and manage them from your laptop as if they were local, with worktrees, terminals, dev servers, and automations for every repository.
Is Berth a CLI tool or a desktop app?Both: berthd is a daemon that runs on each box, berth is the laptop CLI and background agent, and there's a Tauri/React desktop app on top that bundles the CLI and the Linux daemon binaries.
How do I get it running?On each box, run the install script as the user your agents will run under; it downloads berthd, verifies checksums, installs it without root, starts it as a systemd user service (launchd on macOS), and prints a one-time pairing link. Then install the Berth Mac app or the Linux CLI and paste in that link, or run 'berth add ssh' to pair a box over SSH in one step.
Any install pitfalls I should know about?The pairing link is single-use and expires after ten minutes, so you need to add the box right after installing berthd; you can skip the Claude Code/Codex/Cursor integration hooks with --no-integrations if you don't want them.
Which platforms does Berth run on?The desktop app ships as a universal macOS dmg for Apple Silicon and Intel, and the CLI/berthd also run on Linux (linux-arm64, darwin-arm64, darwin-amd64 release builds), using systemd on Linux and launchd on macOS.
How does Berth secure the connection between my laptop and my boxes?Connections use pinned mutual TLS and a one-time pairing link to add a box, with support for reaching boxes over your own Tailscale network.
Which coding agents does Berth support?Berth is built around Claude Code and Codex, with hooks that also let Cursor report its state, and orchestration (prompt, wait, check, loop, hand off) that works across any of them.
What happens to my agents if I close my laptop or lose Wi-Fi?Nothing - agents run on the box itself, not the laptop, so closing the app, sleeping the laptop, or losing Wi-Fi never stops them; the app is just a view you can close and reopen later.
What is a 'kit' in Berth?A kit is a shareable bundle of project setup - ports, environment, services, hooks and flows - that can be applied to a worktree; kits live in their own repositories, like the Cal.com kit mentioned in the docs.
What are Automations in Berth?Zapier-style flows that run on the box itself, triggered by events, schedules, or GitHub activity, plus plain shell hooks and 'before:' gates for project setup.
What are similar projects?1code, swarm-forge, emdash, ClawTeam, buzz, fractal, overstory, vicoa
Which topics is it in?systemd, tailscale, git-worktrees, kanban, tmux, vps, tauri, ssh, workflow-automation, orchestration, agent-orchestration, git
Creator
cosscom
Size
97 MB
Stars
321
Updated
CommitOct 18Releasev0.3.26Oct 18
Age
16d
Commits · 90 Days