---
url: https://clusto.app/docs/architecture.md
description: >-
  Understand Clusto's daemon, clients, session ownership, persistence,
  streaming, and cluster behavior.
---

# 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](/downloads); 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](/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](/clusto-tunnel#finding-nodes-with-scan-network)).

## 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](/transport) 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](/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](/remote-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.key` in 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; plain `ws://` is
  used only for loopback. Browsers cannot pin node keys, so the web client uses
  `wss://` with a node certificate or the [Clusto Tunnel](/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](/transport).
* **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](/remote-updates#security-model).
* **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](/notes#links-and-the-vault).
* **App and web content**: the desktop and mobile apps run under a strict content
  security policy (no inline or `eval` scripts, 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](/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](/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.
