Install
Read this before you install it.
The daemon spawns claude, which can read, edit, and execute files on your machine. There is no app-level login by default: the security boundary is the network. Anyone who can reach the daemon can, in effect, use your computer.
By default it binds only loopback and your Tailscale IP, and refuses to bind LAN or public addresses unless you explicitly set WATERPLANE_ALLOW_PUBLIC=1 (which then requires a password for LAN devices; strongly discouraged, see SECURITY.md). Keep it that way. Point it only at code you trust. SECURITY.md has the full threat model, and DISCLAIMER.md covers what else you are agreeing to: arbitrary code execution, what leaves the machine when you pick a hosted model, and what a free tier is actually paid with.
Unofficial.
Not affiliated with, endorsed by, or supported by Anthropic. This project ships no Anthropic code: it invokes the claude CLI you installed and are logged into. It works by wrapping that CLI's terminal, which means it reads TUI output with regexes and uses flags that change between Claude Code versions. Expect it to need updates when claude updates. Currently tested against claude 2.1.x.
You use your own account, under your provider's terms. Queued, scheduled and resumed-after-limit runs start sessions without you at the keyboard; whether your plan allows that is between you and the provider — see DISCLAIMER.md.
Claude and Claude Code are trademarks of Anthropic, used here only to name the CLI waterplane drives. waterplane is unrelated to any organisation of a similar name.
You need:
- Claude Code installed (
curl -fsSL https://claude.ai/install.sh | bash, or npm install -g @anthropic-ai/claude-code), and something for it to run on: a paid Claude plan (Pro, Max, Team) or an Anthropic API key — run claude once and sign in — or, with no account, a local model through Ollama. GitHub Copilot works too, as a plugin (install.sh --with copilot). Making a repo work well for Copilot and local models: guide.
- A way for the phone to reach the desktop. Recommended: Tailscale on both, on the same tailnet. It works from anywhere, its device sign-in is the gate, and its HTTPS gives the phone push, install and clipboard. From the same Wi-Fi or over a VPN of your own, a password does the gating instead: without Tailscale. With neither, the daemon binds loopback only and is reachable just from the desktop.
The installer (macOS, Linux, WSL2) brings its own pinned Node, verifies checksums, and adds a waterplane command with start, doctor, service, update and pair:
curl -fsSL https://github.com/waterplane-dev/waterplane/releases/latest/download/install.sh | sh
Or from source, which also needs Node ≥ 22.12 and tmux 3.3+ (every session runs inside it, so it survives a host restart; the installer handles both). The doctor builds what it checks, so it runs before the build:
git clone https://github.com/waterplane-dev/waterplane.git
cd waterplane
npm ci # installs the lockfile exactly; runs no dependency install scripts
npm run doctor # checks claude login, node-pty, tmux, Tailscale, HTTPS, port
npm run build
npm start
npm run doctor (or waterplane doctor) is the first thing to re-run when something misbehaves: it names what is wrong and what to type. The host lists the git repos under ~/dev (or WATERPLANE_ROOT; the doctor says which folder) and prints its address. Plain http://100.x.y.z:8770 works for a first look; for install, push and clipboard on the phone, enable HTTPS + MagicDNS in the tailnet admin console once, then open https://<machine>.<tailnet>.ts.net:
tailscale serve --bg --https=443 http://127.0.0.1:8770
Or use the Android app, which needs no HTTPS: get it on Google Play, or download the APK from the latest release.
Windows, Docker, agent install, notifications, a second phone or desktop, the background service, updating and every environment variable: docs/install.md.