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)

Searching Database…

317 ·GitHub
Shipyard
这是什么？Berth 让你能在远程开发机——VPS、云虚拟机或桌子底下的台式机——上运行 Claude Code 和 Codex 等编程智能体，并像操作本地一样用笔记本管理它们，为每个仓库提供工作树、终端、开发服务器和自动化。
Berth 是命令行工具还是桌面应用？两者都是：berthd 是跑在每台机器上的守护进程，berth 是笔记本端的 CLI 和后台智能体，其上还有一个 Tauri/React 桌面应用，捆绑了 CLI 和 Linux 守护进程的二进制文件。
怎么让它跑起来？在每台机器上，以你的智能体将要运行的用户身份运行安装脚本；它会下载 berthd、校验校验和、以非 root 方式安装、作为 systemd 用户服务（macOS 上是 launchd）启动，并打印一个一次性配对链接。然后安装 Berth Mac 应用或 Linux CLI 并粘贴该链接，或者运行“berth add ssh”，一步完成基于 SSH 的机器配对。
安装上有什么我该知道的坑吗？配对链接是一次性的，十分钟后过期，所以你需要在装好 berthd 后立刻添加这台机器；如果不想要 Claude Code/Codex/Cursor 集成钩子，可以用 --no-integrations 跳过。
Berth 能在哪些平台上运行？桌面应用以同时支持 Apple Silicon 和 Intel 的通用 macOS dmg 发布，CLI/berthd 也能在 Linux 上运行（发布构建覆盖 linux-arm64、darwin-arm64、darwin-amd64），在 Linux 上用 systemd，在 macOS 上用 launchd。
Berth 如何保证我笔记本与各台机器之间连接的安全？连接使用证书固定的双向 TLS，添加机器则通过一次性配对链接，还支持经由你自己的 Tailscale 网络访问各台机器。
Berth 支持哪些编程智能体？Berth 围绕 Claude Code 和 Codex 构建，钩子还能让 Cursor 报告自己的状态，并且提供对以上任意智能体都适用的编排能力（提示、等待、检查、循环、交接）。
如果我合上笔记本或断了 Wi-Fi，我的智能体会怎样？什么都不会发生——智能体跑在机器本身而不是笔记本上，所以关掉应用、让笔记本休眠或断开 Wi-Fi 都不会让它们停下来；应用只是一个视图，之后可以关掉再重新打开。
Berth 里的“kit”（套件）是什么？kit 是一份可共享的项目设置包——端口、环境变量、服务、钩子和流程——可以应用到一个工作树上；kit 存放在它们自己的仓库里，比如文档中提到的 Cal.com kit。
Berth 的自动化（Automations）是什么？类似 Zapier 的流程，跑在机器本身，由事件、计划任务或 GitHub 活动触发，另外还有普通 shell 钩子和用于项目设置的“before:”门控。
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
86.5 MB
Stars
317
Updated
CommitOct 17Releasev0.3.25Oct 17
Age
16d
Commits · 90 Days