Quickstart

01 Before you begin

Clu has two halves. The agent is a single self-contained binary that runs on each machine you want to reach. It owns your terminals, files and containers, and it never leaves your hardware. The dashboard is the web app you open from anywhere; it draws the windows and relays your keystrokes to the agent over an end-to-end encrypted tunnel.

Between them sits a zero-knowledge relay. It forwards bytes it cannot read, because encryption and decryption happen only on your own devices. On most connections it does not forward the session at all: the browser and the agent negotiate a direct WebRTC DataChannel and the relay only introduces them, staying on as signalling and as the fallback for a NAT that will not open. We cover the cryptography in the encryption model.

02 Install the agent

On the machine you want to reach, run the installer. It downloads one binary, checks it against the release's signed manifest, and registers a cluterm command on your PATH. No runtime, no dependencies.

$ curl -fsSL cluterm.com/install | sh

# resolving latest release…
✓ downloaded clud-rs
✓ checksum verified
✓ installed to ~/.cludcode/bin/clud-rs
✓ cluterm → clud-rs
# run `cluterm pair` to link this machine

On Windows, run this in PowerShell instead. It installs the native cluterm agent and registers a logon watchdog:

> irm https://cluterm.com/install.ps1 | iex

✓ downloaded cluterm-rs-windows-x64.exe
✓ checksum verified
✓ installed to %LOCALAPPDATA%\CluTerm\bin\clud-rs.exe
# run `cluterm pair` to link this machine

Under WSL, run the curl line inside your Linux distro; the installer detects WSL on its own. See the downloads page for every platform.

Prefer an app? The CluTerm app installs the agent for you, keeps it running, and sits in your menu bar on macOS, or your system tray on Windows and Linux.

03 Pair the machine

Pairing binds this machine to your account and generates its X25519 identity keypair locally. The private key is written to the agent’s keystore on disk and is never transmitted, not to the relay and not to us.

$ cluterm pair A7X92M

✓ generated device identity (X25519)
✓ registered "MacBook Pro" to your account
# first machine only: your 24-word recovery phrase. Write it down.
  Sync password (hidden as you type, 12+ chars):
✓ Sync password set
→ bringing the agent online… (it keeps running here)

The 6-character code comes from Dashboard → Add device. Codes are single-use and expire after 5 minutes. You type the same sync password in the browser to finish pairing, and the agent stays running in that terminal. First connection from a new browser is pinned TOFU (trust-on-first-use), so a swapped key is rejected on every later connection.

04 Connect & run

Open cluterm.com/dashboard in any browser, click your machine, and a terminal opens straight into a persistent session. Keystrokes are AES-256-GCM encrypted in the browser, forwarded as opaque ciphertext, and decrypted only by the agent.

• Keep the agent running. cluterm pair leaves it running in its terminal with a live status screen. After a reboot, or if you close it, start it again with cluterm start; cluterm stop shuts it down. On Windows, the installer's scheduled task starts it at sign-in.
• List paired machines and their status from any device with cluterm list.
• Everything is multi-surface. The same session is reachable from any browser you sign in on, laptop or phone.

05 How it works

A connection is a tunnel, not a copy. Your code, processes and GPU stay on your hardware; Clu only carries the encrypted window into them.

Browser / iOS ──AES-256-GCM──▶ [ relay ] ──AES-256-GCM──▶ Agent (your machine)
   encrypts ciphertext only decrypts → PTY
   decrypts ◀────────────── cannot read ◀────────────── encrypts

session key: X25519 ECDH, ephemeral per connection (forward secrecy)
transport: reverse tunnel, no inbound ports, works behind NAT

The dashboard and billing live on standard cloud infrastructure (Next.js, Supabase, Stripe), but those services only ever see account metadata, never the contents of a session. The relay is a stateless WebSocket proxy with a near-constant memory footprint, which is why the model stays cheap at scale.

06 Sessions

Every terminal is a real shell on your machine, held by the agent’s session daemon. Close the tab, lose Wi-Fi, switch from laptop to phone: the session keeps running. Reattach and the agent replays the existing pane content, so you never land on a blank screen.

• Named, multi-session. A session-index byte routes each window to a specific session, so you can keep main, tests and deploy side by side.
• Shared PTY with reference counting. Open the same session from two devices and both see it live; the PTY is only torn down when the last viewer disconnects.
• Latency comes down to the network between you and the machine. Once a direct WebRTC path opens, our relay steps out: the path is peer-to-peer where the two networks allow it, and goes through a TURN relay where they don’t.

07 The desktop

The dashboard is a spatial window manager built in React. Open, drag, resize, minimize, maximize, tile and cascade windows, each one backed by real protocol messages over the encrypted socket. Minimized windows dock to a taskbar that also shows your sessions, hostname, uptime and a clock, for a genuine “desktop OS” feel.

Useful gestures: double-click a title bar to maximize, Esc closes the focused window, and the launcher groups apps into Develop, Services and Tools rather than dumping them alphabetically.

08 The apps

Everything opens from the launcher. These are the apps you will live in; the rest (Mesh Talk, Devices, Session Canvas, Projects, Memories, Journal, Home Devices, Tasks, Services and Notifications) are a click away.

09 Agent supervision

This is the part Clu is built for: an AI agent runs on your machine, with your tools and your GPU, and you supervise it from anywhere. When a run needs you, Clu, the cat in the corner of the desktop, pops up the plan or diff, and its approvals panel lists every active run step by step.

● PLAN PROPOSED Refactor auth module · 3 files

  + export function validateToken()
  - const token = req.headers.auth
  + const token = req.headers.authorization

  [ approve ] [ reject ] [ ⛔ emergency stop ]

Plan review, per-step diffs, approve/reject and a hard emergency stop all flow over the AGENT_* protocol messages. On a phone, a strip at the bottom of the screen opens the same approvals.

10 Cross-device exec

Your machines can talk to each other. From your iPad you can ask Clu to run something on your home server, and it executes where the work actually lives:

you › run the backup script on my home server
clu › executing on home-server…
✓ backup complete · 2.4 GB synced

Under the hood this is run_on_device / REMOTE_EXEC, which travels over the relay’s encrypted WSS by default. An optional, feature-flagged path negotiates a direct UDP hole-punch between peers for lower latency, falling back to the relay automatically if the punch fails.

11 Encryption model

Clu is end-to-end encrypted. The three primitives below do the work, and the threat model is simple: a breach of our infrastructure, or a subpoena served on us, yields only ciphertext we hold no key for.

Keys are generated on your machine during pairing and stay there. Read the full write-up on the security section of the homepage, or the architecture reference for the wire format down to the byte.

12 Trust boundaries

Each boundary is explicit about what it trusts and what it doesn’t:

13 Handsets: what holding one means

A K10 or CYD-C5 handset is its own device in your account. It pairs with a provisioning code, pins your owner root by fingerprint, and you approve its keys on your head node. Then machines admit its sessions as a cosigned peer: the same class as your own browser. Two things about holding one are true today:

• Its keys are stored unencrypted. The identity and signing keys, the device token and your Wi-Fi password sit in the board's flash (NVS) in clear. Anyone holding the board can read them over its USB cable. Erasing the pairing on the board does not remove them; a Fresh install from the flasher does.
• Its tool calls are confined to what a handset needs. On a machine running agent 0.12.589 or newer, a handset may call only its four canvas tools and the read-only views a chat turn has; run_on_device, files, terminals and the rest are refused. Anything more is a grant you issue on that machine: named capabilities, a time limit, bound to the handset's key, every use sent to your phone. A machine still on an older agent runs a handset's calls with your full power until it updates.

So treat a lost handset like a lost laptop: remove it in the dashboard, and its refresh, dialing and new sessions stop at once. Anyone can flash one from the handset flasher, no account needed; pairing it still takes you, signed in on the dashboard or on your head node with cluterm handset pair. A handset can never be an account's first device: pair a computer first.

14 CLI reference

The cluterm binary is the whole agent. The commands you’ll use most:

15 Troubleshooting

The dashboard says my device is offline

Check the agent is running with cluterm status. If the reverse tunnel dropped, cluterm start re-establishes it. The agent needs only outbound 443 and no inbound ports, so it works behind NAT and most corporate firewalls.

Pairing fails with “invalid signup token”

Codes are single-use and live for 5 minutes. Generate a fresh one from Dashboard → Add device and re-run cluterm pair.

A new browser is refused after I reinstalled the agent

That’s TOFU working as intended: the device’s pinned key changed. Remove the old device from the dashboard and pair the machine again with a fresh code.