Appearance
Architecture
System Overview
Clusto has two operating modes:
Standalone mode (default): A single clustod daemon manages sessions locally. Clients connect over WebSocket.
Cluster mode: a few clustod nodes form a leaderless peer group. Every node is a co-equal authority: it owns the session processes it spawns, applies writes locally, and gossips each change to all peers. There is no leader, no election, and no quorum. A node going offline never stalls the rest of the cluster; on reconnect, anti-entropy merges any state that diverged while it was away.
Peer WS :9179
+-----------+ <--------------------> +--------------+
| clustod | gossip + merge | clustod |
| Node A | <--------------------> | Node B |
| | | |
+-----+-----+ +------+-------+
| client WS :9178 | client WS :9178
| |
+-----v-----+ +------v-------+
| clusto CLI| | clusto CLI |
+-----------+ +--------------+Components
Clusto is made up of a few cooperating pieces:
clustod- the daemon. Owns and supervises agent and shell sessions, serves the client WebSocket protocol, persists session/task/history state, runs the task scheduler, sends notifications, and (in cluster mode) gossips state to peers.clusto- the command-line client. Connects to a daemon over WebSocket to create, attach to, send to, list, and kill sessions, adopt running processes, and inspect the cluster.- Desktop & mobile app - a cross-platform GUI talking to an installed daemon over the same WebSocket protocol. Install the daemon separately with the install script and CLI wizard; the app provides setup instructions and connects to local or remote nodes without managing a local service or bundling the CLI.
All pieces speak the same JSON wire protocol (see Protocol); only terminal output uses a binary frame.
Desktop node discovery
In the desktop app, Connection > Scan Network searches Tailscale, the local network, loopback, and Docker for Clusto daemons. For the desktop machine itself, the scan probes both 127.0.0.1 and the machine's own Tailscale interface. This finds local daemons whether they listen on loopback, all interfaces, or only the Tailscale address, while showing one entry when both probes reach the same daemon. In the native apps the scan also dials the tunnel endpoints saved in your connection profiles and lists the nodes it reaches as Clusto Tunnel entries (see Clusto Tunnel).
How it works
Sessions
A session wraps one running process - an agent CLI (SDK or interactive) or an arbitrary shell. The owning daemon assigns each session a UUID, supervises the process, and fans its output out to every attached client over the session's output stream. Two session modes exist:
- PTY: an interactive terminal; output is raw terminal bytes rendered by the client's terminal emulator, and keystrokes and resizes flow back to the process.
- SDK: a headless agent driven turn-by-turn; each prompt runs the provider CLI and streams structured JSON the client renders as a chat transcript. The provider's own conversation id is threaded across turns so context is kept.
In a cluster, the node a client connects to does not necessarily own a session it creates. An explicitly targeted session starts on the selected node; in the app, New Session and Quick New Session use the selected project's pinned node. If that node is offline, creation stops with an error instead of falling back to the connected node. A request without a node target starts on the connected node. Session metadata is then gossiped to all peers. Requests that must reach the live process, including claims, input, resize, and output subscription, are routed to the owning node.
When an operator assigns a custom session name, the owning daemon persists it for the live session and pushes the update to every connected client. This also updates clients connected through another cluster node, and clients that connect later receive the saved name with the session metadata.
Output streaming and resume
Each session has a bounded, replayable output stream. Clients subscribe to it live and can resume from a sequence cursor after a reconnect without losing output. See Transport & Resume for the replay ring, resume, and keepalive policy.
Persistence
Each daemon persists session metadata, tasks, and history to a local SQLite database in its platform data directory. On startup it restores sessions for history display without re-spawning processes; metadata changes are written back.
Task scheduler
A scheduler wakes on a fixed tick, runs any due tasks (one-shot, interval, or cron), and drives each run as an ordinary PTY session whose output streams to clients. See Tasks.
Notifications
The daemon watches each PTY session's terminal title to detect working and idle transitions. It stores the current working state in the authoritative session metadata and shares updates with clients and cluster peers, which keeps terminal sidebar spinners in sync even when a client is not attached to that terminal's output. Idle transitions are also relayed to connected clients for an in-app desktop popup/sound. Notifications are local to the app; there are no remote push backends. A backgrounded mobile app instead polls the daemon's /notifications HTTP endpoint for a cluster-wide feed.
Updates
The desktop and mobile app and the daemon and CLI fetch updates over the air from a configured manifest URL. Updating a daemon always stages and installs the matching CLI as the same release unit. See Remote-URL Updates.
Concurrency model
The daemon is an async, multi-task service. At a high level:
- Sessions are held in an in-memory map with per-session locking, so attaching, reading, and writing different sessions do not contend.
- Each session has bounded broadcast channels that fan output out to all attached clients; a slow client is shed rather than allowed to stall the others.
- Database writes are serialized and offloaded to a blocking thread pool so they never block the async runtime.
- In cluster mode, replicated state is versioned and snapshot-able, and the set of connected peers is dynamic.
Security
- Client auth: token-based, constant-time comparison (timing-attack resistant). The node token or the shared cluster token grants full access. Repeated failures from one IP address are rate-limited (10 in 60 s block it for 5 minutes). There is no separate low-privilege login password: a new node is adopted with a one-time pairing code (or a reusable pairing password of at least 16 characters) instead of a shared password. Only a salted verifier of it is stored, and ten wrong codes in 15 minutes lock pairing on the node (the lock doubles on each repeat, up to 24 hours).
- Node identity: each node has its own key, created on first start in
identity.keyin the data directory. Clients and peers pin the key the first time they reach a node and refuse a node that later presents a different one, so a stolen address or a man in the middle cannot take over a known node. After a deliberate reinstall, trust the new key from the Cluster view. - Transport: the peer link between nodes is always TLS with mutual key authentication and the node keys above, never plain
ws://. The desktop and mobile apps and the CLI also reach nodes over key-pinned TLS; plainws://is used only for loopback. Browsers cannot pin node keys, so the web client useswss://with a node certificate or the Clusto Tunnel relay. Credential-bearing routes on the client port refuse unencrypted requests from other machines unless they come from loopback, Tailscale, or a network listed in[transport] plaintext_networks. See Transport & Resume. - Session credentials: a session that runs as a non-root OS account other than the daemon's gets a limited credential instead of the node token: it works only for that account's own sessions, chats, and files, only from the same machine, and stops working as soon as the session ends. Clusto Assistant sessions get a narrower assistant credential even when the daemon runs as that account. The credential is passed in the session environment (
CLUSTO_TOKEN). - Signed releases: every daemon, CLI, and app update, and the published feature flags, are signed with a Clusto release key. Clients and nodes verify the signature, size, and hash and refuse downgrades; the installers verify them too. See Remote-URL Updates.
- Files on the node: the daemon runs as root while sessions run as ordinary accounts, so any path an account controls (a Notes vault, a chat workspace, agent configuration) is opened without following links, and a link or a file with a second name that points elsewhere is refused or skipped. See Notes.
- App and web content: the desktop and mobile apps run under a strict content security policy (no inline or
evalscripts, no framing by other sites), agent content is never allowed to run scripts, images in replies load only when you click Load image, and design previews render with scripts disabled. The web client lives on its own origin,web.clusto.app, with the same restrictions. See Web Client. - Accounts: sign-ins last 30 days from their last use, sensitive account changes ask you to sign in again, and an account can turn on two-factor authentication. See Accounts & Licensing.
- Token generation: 32 random bytes, hex-encoded (256-bit entropy). A hand-set node or cluster token shorter than 32 characters is accepted, but the daemon logs a warning at startup because it can be guessed offline.