Appearance
Configuration
Daemon Configuration
The daemon reads its config from a TOML file at the platform-specific config directory. On first run, a default config with an auto-generated auth token is created.
Config File Location
Determined by the directories crate using ProjectDirs::from("dev", "vazac", "Clusto"). On Linux the normal path is ~/.config/clusto/config.toml. Run clusto daemon status to print the exact config path selected on the current machine.
The config file is automatically created by clusto install, which runs an interactive wizard to set these values. You can also create or edit the file manually.
When the daemon is launched with --config <path>, Clusto anchors related paths to that config location. In the default layout this means:
...\config\config.toml...\data\for the SQLite DB, logs, and pasted-file attachments
This is especially relevant for the Windows service install: the service runs as LocalSystem, but Clusto pins --config to the installing user's roaming profile so attachments and other daemon data stay under that same user profile instead of C:\Windows\System32\config\systemprofile\....
Moving a Node from Hive to Clusto
Clusto 1.14.5 and later use layout epoch 2. When an A0 Hive node updates to such a release, a detached migration helper verifies the prepared rollback set, stages the matching clustod and clusto binaries, stops the old service, moves the configured state, starts clustod, and checks the expected version and node name. Linux uses a transient clusto-layout-migration systemd unit. Windows uses the ClustoLayoutMigration scheduled task as SYSTEM.
Inspect a node without modifying it. Use the binary name that currently owns the layout:
bash
hived migrate-layout --dry-run # before the A1 handoff
clustod migrate-layout --dry-run
clustod migrate-layout --dry-run --jsonOn Windows the daemon is a GUI-subsystem program, so the dry run prints nothing in a console unless the output is piped, for example & "C:\Program Files\Hive\hived.exe" migrate-layout --dry-run | Out-String. clusto doctor is the easier check; see Moving from Hive to Clusto.
If a service uses an explicit config path, pass that same path with --config. The report includes old and new paths, collisions, service-manager support, rollback readiness, and the combined ready_for_cutover result. When the cutover cannot run, the dry run prints a cutover blocked by: ... line and the JSON report carries the reason in automatic_cutover_blocker. A node still running hived that skips the automatic cutover also logs a Clusto layout cutover skipped warning with the same reason; read it with clusto logs daemon --node <id>.
If the Clusto data directory already exists, the cutover merges the Hive data into it entry by entry instead of refusing. This is the normal case on Windows, where the Clusto desktop app writes its own log files into the same per-user data directory a per-user daemon uses. Only an entry with the same name on both sides is a collision. Rollback moves back exactly the entries the cutover brought in and leaves the directory's own files alone.
The cutover requires a clusto CLI of 1.14.5 or newer, not the exact daemon version; the CLI is refreshed after the cutover. A cutover that failed and rolled back is retried once by each newer daemon version, never by the same or an older one, so it cannot loop. Before the retry, the staged clustod and clusto binaries left by the failed attempt are removed, but only when they are byte-identical to what that attempt staged.
During the migration overlap, environment lookups prefer CLUSTO_* and fall back to HIVE_*. Child agent processes receive both forms. Discovery also browses _clusto._tcp.local. and the legacy _hive._tcp.local. announcement, then deduplicates results by node ID.
If a handoff must be reversed, run:
bash
clustod migrate-layout --rollbackRollback restores the checksummed A0 daemon, CLI, service definition, and recorded Hive paths. It refuses to overwrite unexplained data. The explicit --force-recovery option preserves each conflict under the migration journal's recovery-conflicts/<migration-id>/ directory before continuing.
While no cutover is in flight, the rollback backup is refreshed to the daemon binary the node currently runs, so a rollback restores the latest legacy daemon rather than the one from when the backup was first taken.
The cutover itself moves only config.toml. On every start, a migrated node moves what stayed in the Hive config directory into the Clusto config directory: TLS certificates under tls/, cluster_preferences.json, and config backups. A name the Clusto directory already holds goes to a hive-leftovers/ subfolder there; nothing is overwritten or deleted. Old Hive desktop profiles (profiles.json) always go to hive-leftovers/, since Clusto never imports them. Emptied Hive directories are removed. Config entries that pointed into the Hive config or data directory (tls_cert, tls_key, audit_log_path, default_working_dir, [notes] local_dir, trusted_dirs) are repointed when the old file is gone and the new one exists.
On load, the daemon also repoints a retired update endpoint. An [update] manifest_url on hive.vazac.dev or dl.vazac.dev, or the retired manifest-unstable.json on the clusto.app hosts, becomes the release track https://clusto.app/. A value received from a peer is normalised the same way. A manifest on any other host is left alone.
Desktop-client migration is separate from node-layout migration. See Moving from Hive to Clusto before installing the new application.
Full Config Reference
toml
# Client API binding address. Default "0.0.0.0" (all interfaces); "127.0.0.1"
# keeps the client API on this machine. All interfaces is safe: the app, CLI and
# peers always use encrypted, key-pinned connections, and credentials are
# accepted over plaintext only from loopback, Tailscale and the networks listed
# in [transport] plaintext_networks. The cluster peer port still listens on all
# interfaces when this is a loopback address.
bind = "0.0.0.0"
# Client WebSocket port.
port = 9178
# Auth token for client connections. Auto-generated (64 hex characters) if
# omitted. A hand-set token shorter than 32 characters can be guessed offline, so
# the daemon logs a warning at startup; remove the line to get a strong one.
token = "a3f8b2c1d4e5..."
# Pairing code or password that lets the app or another node take over this node
# without copying its token. Stored only as a PBKDF2 verifier; the code itself is
# never written. Manage it from Configure Node > Pairing code or `clusto pairing`
# rather than by hand. See Node Identity & Pairing.
# [pairing]
# verifier = "..."
# salt = "..."
# iterations = 600000
# kind = "generated" # or "custom"
# created_at = 1760000000000
# expires_at = 1760086400000 # optional, unix milliseconds
# single_use = true
# Networks allowed to use the client port's credential routes (/ws,
# /notifications, /metrics, /clients/...) WITHOUT encryption, in addition to
# loopback and Tailscale. CIDR ranges or single IPv4/IPv6 addresses. Reloaded
# without a restart. Empty by default.
# [transport]
# plaintext_networks = ["192.168.1.0/24", "10.0.0.5"]
# Extra browser origins allowed to open the client WebSocket and read /identify
# and /notifications cross-origin, on top of the app's own origins and
# https://web.clusto.app. Only needed for a self-hosted web client or a dev
# frontend. Requests without an Origin header (CLI, app, peers) are unaffected.
# Read at startup: a change needs a restart.
# allowed_origins = ["https://clusto.example.lan"]
# Path to the Claude CLI binary. A new config records the resolved absolute
# path when claude is found, else the bare name for a PATH lookup.
claude_bin = "claude"
# Human-readable name for this node. Shown in cluster status.
# display_name = "my-node"
# Default working directory when client sends "." as working dir.
# default_working_dir = "/home/user/projects"
# Extra arguments appended to every Claude session this node spawns (both
# interactive PTY sessions and headless SDK sessions). Alias: claude_extra_args.
# Arguments already present from the command registry or the caller are not
# duplicated.
# arguments = ["--dangerously-skip-permissions"]
# Default OS user new sessions run as when neither an explicit run_as_user nor a
# project-level user mapping is provided. Empty / absent runs sessions as the
# daemon process user. Prefer a non-root account: an agent reads the credentials
# and settings of the account it runs as, and the Claude CLI refuses
# --dangerously-skip-permissions under root, so root-spawned bypass-mode team
# members cannot start at all.
# default_session_user = "clusto"
# Directory roots pre-trusted for Claude sessions, terminal and headless (Unix
# only). Before a claude session spawns with a working dir under one of these
# roots, the daemon marks that folder trusted in the spawn user's ~/.claude.json
# so input sent to a fresh session before anyone attaches is not swallowed by
# Claude's "trust this folder" dialog. Respects run_as_user /
# default_session_user (it writes that user's ~/.claude.json, chowned to them).
# trusted_dirs = ["/home/clusto/projects", "/srv/work"]
# Folder chats without a workspace run in (default: ~/clusto of the chat's
# OS user), and the folder named and replicated chat workspaces are created in
# (default: ~/clusto-chats of the chat's OS user). Both must be absolute and are
# editable live under Node settings > Session Defaults.
# default_chat_dir = "/srv/clusto/chat"
# chat_workspaces_dir = "/srv/clusto/chat-workspaces"
# Tracing-filter directive for the daemon's log subscriber.
# Default is "warn" (errors and warnings only), with cluster peer lifecycle at
# "info" and the tunnel stack capped at "error". Set to "info" or "debug" while
# reproducing an issue, then revert. Accepts the same syntax as RUST_LOG, e.g.
# "clusto_daemon=debug,hyper=warn". The RUST_LOG env var, when set, takes
# precedence over this field.
# log_filter = "info"
# Optional: agent-idle detection tuning.
# The daemon watches each PTY session's terminal title to detect when an
# interactive agent CLI stops working. This drives the in-app desktop
# popup/sound and the durable session name; there are no remote push channels.
# Omit this section to use the built-in Claude/Codex/OpenCode rules.
# [[notifications.agent_detection]]
# name = "claude"
# working_title_regex = '^\s*[\x{25D0}\x{25D1}]' # Claude circle spinner
# Cluster identity and peers. The daemon writes this section on first start
# with a generated node_id and cluster_token, so every node has one; a node
# with no peers runs on its own.
[cluster]
# Auto-generated node UUID. Do not set manually.
# node_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
# Peer node addresses in host:peer_port format.
peers = ["10.0.0.2:9179", "10.0.0.3:9179"]
# Port for inter-node peer WebSocket communication.
peer_port = 9179
# Shared secret for peer authentication. Must be identical on all nodes.
# Auto-generated when empty; set the same value on every node of a cluster.
cluster_token = "shared-cluster-secret"
# Nodes allowed to control this one (node UUIDs). Absent: every node of the
# cluster may. A list allows only those nodes; this node itself always may.
# Node-local, never replicated. While set, this node refuses the cluster token
# as a client credential. Also set with `clusto node controllers` or Configure
# Node > "May control this node". See Clustering > Who may control a node.
# controllers = ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]
# Removed keys: heartbeat_interval_ms, election_timeout_min_ms,
# election_timeout_max_ms and min_quorum belonged to the old leader-based
# cluster. Leaderless clustering ignores them, and the next config save drops
# them from the file.
# This node's client-facing addresses advertised to peers and clients.
# The first entry is treated as primary.
# If omitted, Clusto auto-detects an address from the local machine.
# advertise_addresses = ["10.0.0.1:9178"]
# Human-readable name for this node in cluster context.
# Overrides top-level display_name when set.
# display_name = "node-a"
# Optional: Clusto Tunnel (premium) - Tailscale-free reachability for this node.
# Off by default; normally toggled from Settings > Cluster in the app, not by
# hand. Changes take effect after a daemon restart. See the Clusto Tunnel page.
# [tunnel]
# enabled = true
# Optional relay override; defaults to the Clusto-hosted relay.
# relay_url = "https://relay.clusto.app:8443"
# Web relays allowed to reach this node on behalf of signed-in browsers (endpoint
# ids, hex). Absent = the clusto.app relay; an empty list turns web relay access
# off. Only set it for a self-hosted relay. Read at startup.
# trusted_web_relays = ["<relay endpoint id>"]
[notes]
# Markdown notes vault, S3-backed with a per-node local cache. See the Notes page.
enabled = true
# S3-compatible bucket (sync is disabled without it; the vault stays local-only).
bucket = "my-notes"
# Endpoint for non-AWS providers (MinIO/R2/B2). Omit for AWS S3.
# endpoint = "https://s3.amazonaws.com"
region = "us-east-1"
# Credentials. Omit to fall back to AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY.
# access_key = "AKIA..."
# secret_key = "..."
# Local vault directory. `~` expands to home; defaults to <data_dir>/notes.
local_dir = "~/.clusto/notes"
# OS account whose home roots a relative or `~` local_dir. With `user` set and
# no local_dir, the vault is ~/.clusto/notes in that account's home. Node-local.
# user = "ubuntu"
# Background pull cadence in seconds (minimum 60).
sync_interval_secs = 300Full-text search runs natively inside the daemon - no external tools required. Chats that link notes choose their provider and model through the shared New chat dialog. See Notes for the complete feature reference.
OpenCode
OpenCode is a CLI provider. Install it on every node that runs OpenCode agents:
bash
npm install -g opencode-aiAuthenticate as the same OS account Clusto resolves for the chat or team. For a normal OpenCode provider, run the login command and select the upstream provider you want OpenCode to use:
bash
opencode auth loginThe login is stored for that OS account. If clustod runs agents through default_session_user or a Project's Run As User, logging in as your shell account or as root does not configure that agent account.
Enter OpenCode models in provider/model form.
Override the binary or append node-wide arguments with the normal agent table:
toml
[agents.opencode]
bin = "/opt/opencode/bin/opencode"Native OpenRouter API
OpenRouter is independent of OpenCode. Clusto calls the native OpenRouter HTTP API directly, streams its response, maintains conversation history, and runs workspace tools in the daemon. Configure one write-only key for the cluster from Settings > Account > OpenRouter API, or press F1 and run Configure OpenRouter API key.
Saving or replacing the key distributes it to every connected node and applies it to the next OpenRouter turn without restarting the daemons. Nodes that are offline during a change converge on the latest value when they reconnect. The app never reads the saved key back from a daemon.
Each node persists its replica in private config.toml settings:
toml
[openrouter]
api_key = "sk-or-v1-..."
updated_at = 1700000000000The app manages this section and its convergence timestamp. Do not configure nodes one by one. Clear stored key distributes removal of the shared key in the same way.
A daemon may instead receive a local environment fallback:
bash
OPENROUTER_API_KEY=sk-or-v1-...This value is used only when no cluster key exists. It is not distributed, so environment-provided keys can differ between nodes and must be changed in each node's service environment. After the cluster key is cleared, the settings card reports the connected node's environment fallback when one is present.
OpenRouter uses native model ids such as anthropic/claude-sonnet-4-5. With no explicit model Clusto sends openrouter/auto. The cluster key belongs to the daemon cluster, not the chat's Run As user. Run As still controls filesystem and command tools. No OpenCode binary, OpenCode login, or [agents.openrouter] entry is used for OpenRouter sessions.
OpenCode models are probed with opencode models. OpenRouter models come from the public OpenRouter catalog. You can add or override picker entries in the same model catalog used by other providers:
toml
[[models.extra.opencode]]
id = "anthropic/claude-sonnet-4-5"
tier = "balanced"
[[models.extra.openrouter]]
id = "anthropic/claude-sonnet-4-5"
tier = "balanced"See Chats and Teams for provider-specific runtime behavior.
GitHub ([github])
The GitHub view stores its settings in a [github] section. Manage it from Settings > GitHub; do not edit nodes one by one.
toml
[github]
updated_at = 1790000000000
[[github.accounts]]
id = "5d2f8a40-9c1e-4b7a-8e63-1a0c7f2b9d44"
name = "Personal"
host_node_id = "a1b2c3d4-..."
# Optional (defaults shown): standby_node_ids = [] (ordered node ids that poll
# in turn while the host is offline), poll_interval_secs = 60 (15 to 3600),
# merge_method = "squash" ("merge", "squash" or "rebase"),
# pinned = [] and hidden = [] (lists of "owner/name").
pinned = ["acme/api"]
# Written on the host and standby nodes only, for accounts they serve.
[github.tokens.5d2f8a40-9c1e-4b7a-8e63-1a0c7f2b9d44]
token = "github_pat_..."
login = "your-github-login"accountsis cluster-shared: the whole list replicates to every node, and a node adopts a peer's copy when itsupdated_atis newer (whole-list last-writer-wins, so removing an account needs no tombstone).tokensis keyed by account id: a GitHub token exists only on the nodes of the account's host list (the host node, then itsstandby_node_ids). It is copied over the encrypted peer links to those nodes only, never sent to a client and never logged. Removing an account drops its token, andloginis the account the token authenticated as when it was saved.pinnedrepositories are listed first and always polled as active;hiddenones are left out of the view and never polled.
See GitHub for the setup fields, standby nodes and the token security guidance.
Model catalog ([models])
Controls the model list offered when picking an agent for a team member (see Teams). Optional - the defaults work with no configuration.
toml
[models]
# How long a fetched per-provider model list is cached. Default: 6.
refresh_hours = 6
# Consult the keyless OpenRouter public index for ids released after this
# build. Set false on nodes that must not reach the internet. Default: true.
openrouter = true
# Extra or overriding entries, keyed by provider id. An entry whose `id`
# already exists overrides that model's label and tier.
[[models.extra.claude]]
id = "claude-opus-5"
label = "House deep model"
tier = "deep" # fast | balanced | deep
[[models.extra.llama]]
id = "qwen2.5-coder:32b"
tier = "balanced"Live provider probes are used when the daemon's environment has credentials for them: ANTHROPIC_API_KEY (Anthropic /v1/models) and OLLAMA_HOST (or http://127.0.0.1:11434) for local llama tags. OpenCode is probed through opencode models, while OpenRouter uses its public catalog. A subscription-only login has no listing endpoint, so those providers fall back to the bundled catalog. Codex is the exception: its account-specific list comes from the installed codex CLI (codex app-server, model/list). When the CLI cannot answer, only your [[models.extra.codex]] entries are listed, and an empty selection runs Codex's own default model.
Field Details
| Field | Type | Default | Description |
|---|---|---|---|
bind | String | "0.0.0.0" | Interface to bind the client WebSocket server. A loopback value (127.0.0.1, localhost) restricts only the client API and is kept across restarts; the cluster peer server then binds all interfaces so peers can still connect |
port | u16 | 9178 | Port for client WebSocket connections |
token | String | auto-generated | 64-char hex string (256-bit) for client authentication. A token or cluster_token shorter than 32 characters can be guessed offline from the identity proof the node gives any caller, so the daemon logs a startup warning (it never logs the value) |
pairing | Table | (none) | The [pairing] section: a PBKDF2-HMAC-SHA256 verifier, salt, iterations, kind (generated or custom), created_at, optional expires_at (unix ms) and single_use. Written by the daemon when you create a code; see Node Identity & Pairing. A top-level user_secret (alias adoption_secret) from an older config is read once at startup: 16 or more characters become a custom pairing password, a shorter one is disabled ("reset required"), and the plaintext is removed from the file |
transport.plaintext_networks | Vec<String> | [] | CIDR ranges or single IPv4/IPv6 addresses (IPv4-mapped forms included) whose clients may use the client port's credential routes without TLS, in addition to loopback and Tailscale. Hot-reloaded; invalid entries are logged and skipped. See Node Identity & Pairing |
allowed_origins | Vec<String> | [] | Extra browser origins (scheme://host[:port]) allowed to open the client WebSocket and read /identify and /notifications cross-origin, besides the app's own origins and https://web.clusto.app. No wildcards, paths, * or null; invalid entries are logged and skipped. A foreign origin gets 403 on the WebSocket and no CORS headers. Requests with no Origin header are never affected. Needs a restart |
claude_bin | String | resolved claude path, else "claude" | Path or name of the Claude CLI binary |
display_name | Option<String> | (none) | Human-readable node name, shown in cluster status |
default_working_dir | Option<String> | (none) | Default working directory for new sessions |
default_pty_shell | Option<String> | (none) | Program new terminal sessions run when no command is requested; see Commands. Unset falls back to claude_bin |
arguments (alias claude_extra_args) | Option<Vec<String>> | (none) | Extra arguments appended to every Claude session (interactive PTY and headless SDK); args already supplied by the command registry or caller are not duplicated |
default_session_user | Option<String> | (none) | OS user new sessions and durable Chats run as when no more specific session user applies; empty/absent runs as the daemon process user. On Unix, a root-effective Chat launch is rejected. Prefer a non-root account, see Chats and Teams |
default_chat_dir | Option<String> | (none) | Absolute folder where chats with no workspace run on this node. Unset uses a clusto folder in the home of the OS user the chat runs as. Shared by every no-workspace chat on the node and not replicated; editable under Session Defaults > Chat Folder and applied live, see Chats |
chat_workspaces_dir | Option<String> | (none) | Absolute folder that holds named chat workspaces created from the app and the workspaces of chats replicated onto this node, one subfolder per workspace. Unset uses a clusto-chats folder in the home of the OS user the chat runs as. Existing chats keep their folder; editable under Session Defaults > Chat Workspaces Folder and applied live, see Chats |
trusted_dirs | Vec<String> | [] | Directory roots pre-trusted for Claude sessions, terminal and headless (Unix only); see below |
[sandboxes] | Table | {} | Maps an OS user to an Incus container name (for example clusto-factory = "clusto-factory"). Every process Clusto runs as that user then runs inside the container, as the same user. Linux, daemon as root, Incus required; applies on hot reload to new processes. See Software factory |
log_filter | Option<String> | "warn" | Tracing filter directive (the built-in default also logs cluster peer lifecycle at info). RUST_LOG env var overrides this when set. Logs go to clustod.log in the daemon's data directory (rotated at 100 MiB, 10 files kept) and, when not running as a Windows service, to stderr (the systemd journal for the Linux service) |
output_keep_rows | usize | 50000 | Session output rows kept per session in the database; older rows are pruned every 10 minutes |
output_max_age_days | u32 | 30 | Session output rows older than this are pruned |
drain_timeout_secs | u64 | 10 | Seconds a clustered node waits for in-flight replication on graceful shutdown |
audit_log_path | Option<String> | (none) | JSON-lines audit log of auth, session lifecycle, and cluster changes; audit logging is off when unset |
keyboard_shortcuts | Table | {} | Custom keyboard shortcut bindings shared by every client of the node (command id to chord). Written by the app; do not edit by hand |
ssh_secret_key | Option<String> | auto-generated | Secret that encrypts saved SSH connection credentials at rest. The cluster converges on one shared value. Do not edit by hand |
env | Table | {} | Extra environment variables injected into every spawned process (terminal and agent). On a Windows service, USERPROFILE, HOME, HOMEPATH, and HOMEDRIVE are filled from the config path when not set here |
[agents.<provider>] | Table | detected binaries | bin, args, and headless_args per CLI provider (claude, codex, opencode, copilot, llama); see Teams |
[update] | Table | clusto.app | Self-update manifest URL, token, auto-check schedule, and remote flag fetching; see Remote-URL Updates and Feature Flags |
[knowledge] | Table | enabled | Agent knowledge wiring and backups; see Knowledge. enabled = false turns it off, including Agent Docs sync |
[knowledge] agent_sync | string | "two_way" | Per-node Agent Docs sync mode: "two_way", "receive_only" (cluster items are written here, nothing is sent), or "manual" (nothing automatic; move items from Agent Docs). See Sync modes |
[notes] | Table | local vault | Notes vault location, owning user, and S3 sync; see Notes |
models.refresh_hours | u64 | 6 | Cache TTL for a provider's fetched model list |
models.openrouter | bool | true | Consult the keyless OpenRouter model index |
models.extra.<provider> | Array of tables | [] | Operator-supplied model entries (id, label?, tier?, context_window?) |
openrouter.api_key | Option<String> | (none) | Write-only native OpenRouter credential replicated across the cluster; when absent, each daemon may use its local OPENROUTER_API_KEY environment fallback |
openrouter.updated_at | i64 | 0 | App-managed timestamp used for last-write-wins cluster convergence, including after an offline node reconnects |
cluster.node_id | Option<Uuid> | auto-generated | Unique node identifier, auto-generated on first cluster start |
cluster.peers | Vec<String> | [] | Peer node addresses (host:peer_port) |
cluster.peer_port | u16 | 9179 | Port for peer-to-peer WebSocket connections |
cluster.cluster_token | String | auto-generated | Shared secret for inter-node authentication |
cluster.peer_nodes | Array of tables | [] | Peers with several addresses to try in order ([[cluster.peer_nodes]] with node_id?, name?, addresses, and the pinned identity and identity_updated_at the daemon records); takes precedence over peers when set |
cluster.controllers | Option<Vec<Uuid>> | (absent) | Nodes allowed to control this one. Absent lets every node of the cluster; a list allows only those nodes (this node itself always may). Node-local, never replicated, applied without a restart. While set, the node refuses the cluster token as a client credential. See Who may control a node |
cluster.advertise_addresses | Vec<String> | [] | Client-facing addresses this node advertises to peers and clients; first entry is primary. CLUSTO_ADVERTISE_ADDRESS overrides it |
cluster.display_name | Option<String> | (none) | Node name in cluster context (overrides top-level display_name) |
tunnel.enabled | bool | false | Enables Clusto Tunnel on this node (premium); requires a daemon restart |
tunnel.trusted_web_relays | Option<Vec<String>> | the clusto.app relay | Endpoint ids (hex) of the web relays allowed to reach this node for signed-in browsers; an empty list turns web relay access off. See The web relay. Needs a restart |
tunnel.relay_url | Option<String> | https://relay.clusto.app:8443 | Custom iroh relay URL for tunnel connection setup and fallback |
Node identity file
The node's identity key is not in config.toml. It is identity.key in the daemon's data directory (owner-only, created on first start, never replicated). An older [tunnel] secret_key is moved into it on the first start of this release and removed from config.toml, so the tunnel endpoint id does not change. Back it up with config.toml; see Node Identity & Pairing.
Update and feature flag settings
Beyond the manifest URL, token and auto-check schedule (see Remote-URL Updates), [update] controls the remote feature flag file described in Feature Flags:
| Field | Type | Default | Description |
|---|---|---|---|
update.fetch_flags | bool | true | Fetch flags.json from the manifest base URL. false means no remote kill-switch: built-in defaults and overrides only, and a previously cached copy is not used |
update.flags_interval_secs | u64 | 900 | Seconds between flag file checks; independent of auto_check and interval_secs |
[features] | Table of bool | {} | Node-local release flag overrides by flag id ("some.node_flag" = true). Ignored for cluster-scope flags, which is every current flag |
cluster_features | Table | (unset) | Cluster-shared early access and per-flag overrides set in Settings > Labs. Written by the daemon and synced between peers; do not edit by hand |
manifest_url is a base directory URL. If its last segment ends in .json it is used verbatim, so a node can point at one specific manifest file; anything else gets /manifest.json appended. flags.json resolves in the same directory.
[update] channel is removed: there is one release track. A config that still has it keeps loading. On start the daemon migrates once: channel = "unstable" turns on Settings > Labs early access for the cluster (only if Labs settings were never set), any other value is just dropped, and config.toml is rewritten without the key. See Remote-URL Updates.
toml
[update]
fetch_flags = true
flags_interval_secs = 900
[features]
"some.node_flag" = trueCommands
[[commands]] is the node's shell registry: the named presets the app offers in New Session → Shell, and the names clusto open --shell resolves against. Each entry has a name (unique per node), a resolved program path, optional args, and an enabled flag. On first start the daemon fills an empty registry with whichever shells it finds installed, and on every start it prunes entries whose absolute program no longer exists.
toml
[[commands]]
name = "Zsh"
program = "/bin/zsh"
args = []
enabled = trueEdit them per node from the app: open the node's Node settings in the Cluster view, then Shells. The Program field has a Browse button that opens a file picker on that node, so you pick the program there instead of typing the path; picking one keeps any arguments you already typed after it. The same Browse button is on the custom shell field of the New Session dialog, the project's Default Shell and the node's Default Shell (Custom...) below.
How a session's program is resolved, in order:
- No command sent - the daemon uses the project's own
default_shell(see below) when the request names a project, thendefault_pty_shell, falling back toclaude_bin. - A registry name or program path - the matching enabled entry supplies the program and its
args. Arguments sent with the request replace the entry'sargsrather than extending them. - Anything else - treated as a command line and tokenized into a program plus arguments (quotes and backslash escapes honoured). A value naming an existing file is used verbatim, so unquoted paths with spaces are safe. Arguments sent with the request are appended. This is what the app's Claude agent and Custom... presets and
clusto open --shell "pwsh -NoExit"go through. A program that resolves toclaudeis replaced by the configuredclaude_bin, so a bareclaudealways launches the binary this node is configured with.
Whenever the resolved program is claude, the config-level arguments (legacy claude_extra_args) are merged in, whichever of the three paths produced it.
On Windows the resolved program is turned into something the OS can launch before spawning. npm installs a global CLI as several files in the same folder - claude.cmd plus an extensionless shell shim - and only the .cmd/.exe form can be started; the daemon therefore prefers an executable extension when it looks a program up on PATH, and fills one in when claude_bin points at an extensionless path. Setting claude_bin to the .cmd (or the native claude.exe) explicitly is still the clearest option, and paths containing spaces such as C:\Program Files\... need no quoting in the config file.
The registry also holds a Claude agent entry - the one that starts a Claude session - seeded on first load when the Claude CLI is installed on that node. The app lists the registry one for one, so a node whose registry has no agent entry offers no agent in New Session; add it back from the node's Node settings in the Cluster view with Shells > Add Shell and claude as the program. The agent entry is never selected automatically: New Session preselects the project's default shell, then the node's default_pty_shell, then the shell last used on that node, then the node's first registry entry.
default_pty_shell accepts a registry entry name (Zsh), a program (bash, pwsh, /bin/zsh) or a whole command line, exactly like a project's default_shell; the daemon resolves it through the same registry lookup, and the app matches it against each preset's name, key and program basename, case-insensitively.
Edit it per node in the app under Cluster → node → Configure → Session Defaults → Default Shell. The picker lists that node's registry entries plus Custom... for a raw command line; Auto-detect clears the setting. Any node can be configured, not only the connected one: the request is relayed to the target node, which persists it and announces the new value to the cluster. The connected node applies it live (no daemon restart). Use this same node configuration dialog when the daemon runs on the desktop machine.
Per-Project Node
A project can pin its sessions to a cluster node. Set the node in the app under Projects → Edit → Node. Both New Session and Quick New Session honor the selected project's pinned node, regardless of which daemon the app is connected to.
In cluster mode, creating a project without an explicit node ID pins it to the daemon that receives the create request. This also covers This node during app startup, before the cluster status has supplied that node's UUID.
Clusto does not silently fall back to the connected node when the pinned node is offline. It blocks session creation and reports that the selected project node is unavailable. Bring that node online or explicitly change the project's node before creating the session.
Projects Created by Agents
A chat or terminal agent can create a project when you ask, through the clusto_project_create MCP tool (or clusto project new from inside its session). It works only on the agent's own node, for a folder that the agent's own OS account owns, and every Run as on the project, plus the account its sessions resolve to on that node, must be that same non-root account. Anything else is refused with a message and you create the project in the app. Editing and deleting projects stay with you. Free on every plan.
Clone From a URL and Repository Link
New Project has a Clone from URL option that clones a git repository onto a node and creates the project for it in one step; see GitHub and clusto project clone in the CLI. The project dialog also has a Repository link field (github:owner/name or azure-devops:org/project/repo) that names the project's repository explicitly. A link overrides matching on the git remote and keeps working while the project's node is offline; clear the field to go back to the remote match.
Per-Project Default Shell
A project can pin the command its sessions start with, overriding default_pty_shell for that project only. Set it in the app under Projects → Edit → Default Shell; the options are the target node's registry entries, the Claude agent, or a custom command line. Node default (the default) leaves the project following the node.
The value is stored on the project and replicated cluster-wide, so every client - desktop, web and mobile - and every headless path (clusto open without --shell, scheduled tasks, the quick-session shortcut) starts that project's sessions with the same command. Since the registry is per node, pick the shell after choosing the project's node; switching to a node that cannot resolve the current choice resets the field to Node default.
Session Users and Trusted Directories
default_session_user sets the OS account new sessions run as when nothing more specific applies. Resolution order is: an explicit run_as_user on the request, then the project's run_as_users mapping for this node, then default_session_user. When all are absent, sessions run as the daemon process user (often root when clustod runs as a system service, which is why a non-root default is preferred). It is editable per node from the app under Cluster → node → Configure → Session Defaults → Default User, alongside the node's default shell (see Clustering).
For a terminal session forwarded across the cluster, the destination node applies this fallback when it creates the process. If both the request and project leave the user unset, the session uses the destination node's default_session_user, not the default configured on the connected or forwarding node.
Every picker that starts work names the value it would inherit, so the fallback is never guesswork: New Session and Session as user offer Node default (Zsh) / Project default (ubuntu) entries, and Projects → Edit shows the same on its Default Shell and Run As User fields. Choosing the inherit entry sends nothing, so the daemon resolves the chain at spawn time and a later change to a node default applies without touching the project.
Durable Chats and Notes follow the same chain minus the per-request override: the chat's project run_as_users mapping, then the node's default_session_user, then the daemon process user. New chat prints the account it resolves to. On Unix, Clusto rejects a Chat launch if that account is root. Set Default User to a non-root account in the node's Session Defaults. Leaving it blank is valid when clustod already runs as a non-root account.
trusted_dirs (Unix only) pre-trusts directory roots for Claude sessions, both terminal and headless. On its first interactive run in an unfamiliar folder, Claude Code shows a "Do you trust the files in this folder?" dialog and waits for a keypress; input an orchestrator or team leader sends to a fresh session would otherwise stall behind that prompt. When a claude session is about to spawn with a working directory at or under one of these roots, the daemon marks the folder trusted (hasTrustDialogAccepted) in the spawn user's ~/.claude.json before launch, so the session comes up ready for input. It writes the ~/.claude.json belonging to the resolved session user (honouring run_as_user / default_session_user) and chowns the file to them.
toml
default_session_user = "clusto"
trusted_dirs = ["/home/clusto/projects", "/srv/work"][sandboxes] moves a session user off the host: each entry maps an OS user to an Incus container, and every process Clusto runs as that user runs inside the container instead. See Software factory.
Notifications Fields
All fields live under [notifications].
| Field | Type | Default | Description |
|---|---|---|---|
agent_detection | Array | built-in | Per-agent title detection rules (see below); defaults to the Claude and Codex spinner rules and the OpenCode OC | title prefix |
agent_detection[].name | String | required | Label shown in logs |
agent_detection[].working_title_regex | String | required | Regex matched against the terminal title; a match means "working" |
Agent-Idle Detection (daemon-native)
The daemon watches each PTY session for an interactive agent CLI changing from working to idle, needing no CLI on the host and no per-agent hook. Claude Code uses alternating circle halves (U+25D0/U+25D1) in its OSC window title, while Codex uses an animated braille glyph (U+2800..U+28FF) and OpenCode an OC | title prefix. Each drops its marker once idle, so the built-in title rules detect the transition. GitHub Copilot CLI exposes activity in the rendered terminal instead: Clusto detects its live Working ... esc interrupt footer and clears the working state when that footer disappears. Codex's default title includes its thread GUID rather than a task summary; Clusto uses the spinner for activity detection but discards that opaque GUID when choosing a session label or idle-notification detail. Plain shell titles do not match the title rules. The Copilot footer check is limited to the bottom of the live screen so old transcript text does not mark a session as working.
The idle transition drives the in-app desktop popup/sound. Useful human-readable titles can label the session and are persisted as its durable terminal title. Detection is always on; there are no remote push channels to configure.
To tune or add agents, override agent_detection:
toml
[[notifications.agent_detection]]
name = "claude"
working_title_regex = '^\s*[\x{25D0}\x{25D1}]'
[[notifications.agent_detection]]
name = "codex"
working_title_regex = '^\s*[\x{2800}-\x{28FF}]'
[[notifications.agent_detection]]
name = "opencode"
working_title_regex = '^\s*OC\s*\|'
[[notifications.agent_detection]]
name = "my-agent"
working_title_regex = 'Thinking|Working'Defining agent_detection replaces the built-in defaults, so include the Claude, Codex, and OpenCode rules above if you still want them. To see what title your agent emits (for writing a regex), run the daemon at RUST_LOG=debug and watch the session.
In the Clusto app
While Claude Code, Codex, or GitHub Copilot CLI is working, its terminal entry in the sidebar shows a rotating activity indicator. Clusto removes Claude and Codex's changing title glyph from the displayed session name, so the label stays stable while work is in progress. Copilot's terminal label remains stable because its working state comes from the live footer instead of the title.
When a session goes idle the app raises a native desktop popup and plays a sound (both toggleable, per device, under Settings -> Notifications -> Desktop alerts). The finished notification uses the session's current display name when the idle transition fires, including a contextual Codex name assigned after the terminal started. The same name is stored with the durable background notification. Each terminal in the sidebar gets a bell icon next to its close button to mute idle alerts for that session on this device. These are client-side preferences.
Task Scheduler
Tasks are created and managed through the Clusto app, clusto task, or the WebSocket task messages described in Tasks. Each task has a schedule that controls when it runs.
Schedule Types
One-shot - runs immediately when created, then stops:
json
{ "type": "one_shot" }Interval - repeats every N seconds after each run completes:
json
{ "type": "interval", "seconds": 3600 }Cron - runs on a cron schedule. Clusto uses 6-field expressions with seconds at the front (seconds minutes hours day-of-month month day-of-week). Seconds are mandatory - a bare 5-field expression is rejected:
json
{ "type": "cron", "expression": "0 0 * * * *" }Cron Expression Format
The scheduler uses the cron 0.12 crate and evaluates expressions in UTC. Expressions use six space-separated fields (a seventh optional year field is allowed):
┌──────────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌──────────── hour (0-23)
│ │ │ ┌──────────── day of month (1-31)
│ │ │ │ ┌──────────── month (1-12 or names: jan-dec)
│ │ │ │ │ ┌──────────── day of week (1-7, Sunday=1, or names: sun-sat)
│ │ │ │ │ │
* * * * * ** means "any"; ? means the same but is accepted only in the day-of-month and day-of-week fields. Steps (*/15), ranges (9-17), and lists (1,15) are supported. Day-of-month and day-of-week are combined with AND. The lowercase shorthands @hourly, @daily, @weekly, @monthly, and @yearly are also accepted; @annually and uppercase forms are rejected.
Common examples:
| Expression | Meaning |
|---|---|
0 * * * * * | Every minute at second 0 |
0 0 * * * * | Every hour at minute 0 |
0 0 9 * * * | Daily at 09:00 UTC |
0 0 9 * * Mon | Every Monday at 09:00 UTC |
0 0 9 * * Mon-Fri | Weekdays at 09:00 UTC |
0 0 9 1 * * | First day of every month at 09:00 UTC |
* * * * * * | Every second |
Note: All times are UTC. The scheduler wakes at each task's next fire time, so a task typically runs within a second of its slot (at most 30 seconds late after a system clock jump).
Browser certificate (wss:// for the web app)
The desktop and mobile apps and the clusto CLI always connect to a node with TLS 1.3, pinned to the node's identity key, and need no certificate (see Node Identity & Pairing). A browser cannot pin a raw key, so a node that should be reached directly from the web app, or from any other TLS client that cannot use raw keys (curl, a Prometheus scraper), serves a normal certificate. Set both tls_cert and tls_key in the config file to give those clients wss:// / https://. Without them a browser can still reach the node through the web relay.
Enabling the browser certificate
toml
# Path to the PEM-encoded TLS certificate (full chain recommended).
tls_cert = "/etc/clustod/cert.pem"
# Path to the PEM-encoded TLS private key.
tls_key = "/etc/clustod/key.pem"Both fields must be set: with only one of them the daemon logs a warning at startup and serves no browser certificate. If the files cannot be loaded, the daemon exits at startup with an error. With a certificate configured, the daemon's startup info line (visible with log_filter = "info") reports browser_tls = true.
Renewal and hot reload
A daemon serving TLS re-reads its certificate file every hour:
- Hot reload. Whenever the certificate on disk changes (automatic renewal or a manual
clusto cert), the daemon loads it into the livewss://listener within the hour. No restart is needed. Enabling TLS for the first time still requires a restart (clusto cert --restart). - Automatic renewal. When less than a third of the certificate's lifetime is left (about 30 days for a 90-day Tailscale cert) and the certificate was issued by
clusto cert(a*.ts.netname whose cert and key sit at<config dir>/tls/<name>.crtand.key), the daemon re-runsclusto certitself, at most once every 12 hours. - Other certificates are not renewed. A certificate you installed at another path (certbot, a corporate CA, a self-signed file) is left to you. The daemon logs a warning when it is due; replace the file and the hot reload picks it up.
Generating a Self-Signed Certificate (for testing)
bash
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
-days 365 -nodes -subj "/CN=localhost"For production, use a certificate issued by a trusted CA (e.g. Let's Encrypt / certbot).
Connecting with TLS
CLI: the CLI uses plain ws:// only to a loopback host and raw-key TLS to every other host, so a remote node needs no flag. --tls forces TLS for loopback as well:
bash
clusto --host my-server.example.com ls
# force TLS even on this machine
clusto --tls ls
# or via environment variable
CLUSTO_TLS=true clusto lsEnvironment variables:
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
CLUSTO_TLS | --tls | false | Use TLS also for a loopback host (every other host always uses TLS) |
CLUSTO_IDENTITY | --identity | (none) | Expected node identity (64 hex, clusto identity show prints it). A node presenting another key is refused before the token is sent |
CLUSTO_TLS accepts only true or false; numeric values such as 1 or 0 are rejected by the CLI. For an older running chat session that inherited CLUSTO_TLS=1, override it when running a command:
bash
CLUSTO_TLS=true clusto task lsApp (desktop / mobile / web): there is no manual TLS toggle in the Connect view. The desktop and mobile apps always use raw-key TLS and pin the node's identity, with or without a certificate and by IP address or name. The web app uses wss:// with the node's certificate or the relay; it never opens ws:// from an https page. A browser certificate is issued for a name, so connect by the node's Tailscale MagicDNS hostname (e.g. my-node.tailnet.ts.net), not a bare IP. See clusto cert / the web client page for provisioning a TLS cert per node.
In-session helpers: chat tools (including the Clusto Assistant), team MCP servers, Stop hooks and any clusto CLI run inside a session run on the same machine as the daemon. The daemon serves a plain loopback listener on 127.0.0.1 (random port, same token authentication) and points these helpers at it through CLUSTO_DAEMON_SOCKET. They therefore never depend on a certificate: an expired or broken certificate does not cut them off (CLUSTO_TLS is false for them). The listener is bound to loopback only and is not reachable from the network. If it cannot be bound, the daemon logs a warning and helpers dial the client port with raw-key TLS, pinned to the node identity in CLUSTO_DAEMON_IDENTITY (set for every session).
Inside a session, CLUSTO_TOKEN is the session's own credential, which is the admin token for root and daemon-account sessions and a limited credential for sessions that run as another account (see Session Credentials).
Browser certificate field reference
| Field | Type | Default | Description |
|---|---|---|---|
tls_cert | Option<String> | (none) | Path to the PEM certificate file served to browsers and other TLS clients without raw-key support. No browser certificate is served when absent. |
tls_key | Option<String> | (none) | Path to the PEM private key file. No browser certificate is served when absent. |
Note: The certificate applies to the client-facing port (
port, default 9178). Node-to-node traffic on the peer port (9179) is always TLS 1.3 with mutual, key-pinned authentication and never uses this certificate. See Clustering.
Desktop Client Storage
In the native desktop app, open Settings > This device to inspect files owned by that Clusto client. The Client storage card shows the total used space and lists each client directory separately, including app data, local app data, configuration, cache, logs, downloads, and account state. Duplicate paths are combined into one entry.
Each row shows its absolute path and used size. Select Open folder to open that location in the operating system's file manager, or Refresh to measure the directories again. Clusto also refreshes the measurement when the desktop app starts.
This is client storage on the current desktop, not the database, logs, attachments, or staged updates owned by a clustod node. Those node-local files are reported separately for each node under Settings > Cluster. The web app cannot open browser-managed storage folders and directs you to the native desktop app for this view.
Client Configuration
The clusto client is configured through CLI flags, environment variables, and optional saved connection profiles (profiles.toml in the Clusto config directory, managed with clusto profile).
Environment Variables
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
CLUSTO_HOST | --host | 127.0.0.1 | Daemon host address |
CLUSTO_PORT | --port | 9178 | Daemon port |
CLUSTO_TOKEN | --token | profile, then the local daemon's access file or config | Authentication token |
CLUSTO_NODES | --nodes | (none) | Comma-separated cluster node list |
CLUSTO_TLS | --tls | false | Use TLS also for a loopback host (every other host always uses TLS) |
CLUSTO_IDENTITY | --identity | (none) | Expected node identity (64 hex); a node presenting another key is refused |
CLUSTO_PROFILE | --profile | the default profile | Saved connection profile to use |
During the Hive-to-Clusto overlap each CLUSTO_* variable falls back to its HIVE_* name when unset.
Precedence
CLI flags override environment variables, which override the active profile. When --nodes / CLUSTO_NODES is set, it overrides --host / --port.
Example Shell Setup
bash
# Standalone
export CLUSTO_TOKEN="a3f8b2c1d4e5..."
# Cluster
export CLUSTO_TOKEN="a3f8b2c1d4e5..."
export CLUSTO_NODES="10.0.0.1:9178,10.0.0.2:9178"Cluster Configuration Examples
Two-Node Cluster
Node A (10.0.0.1):
toml
bind = "0.0.0.0"
port = 9178
token = "client-auth-token"
[cluster]
peers = ["10.0.0.2:9179"]
peer_port = 9179
cluster_token = "shared-cluster-secret"
advertise_addresses = ["10.0.0.1:9178"]Node B (10.0.0.2):
toml
bind = "0.0.0.0"
port = 9178
token = "client-auth-token"
[cluster]
peers = ["10.0.0.1:9179"]
peer_port = 9179
cluster_token = "shared-cluster-secret"
advertise_addresses = ["10.0.0.2:9178"]Three-Node Cluster
Each node lists the other two as peers:
toml
# On 10.0.0.1
[cluster]
peers = ["10.0.0.2:9179", "10.0.0.3:9179"]
peer_port = 9179
cluster_token = "shared-cluster-secret"
advertise_addresses = ["10.0.0.1:9178"]No Quorum Requirement
No special configuration is needed for any cluster size. Leaderless clustering has no quorum: every node keeps serving reads and writes for the state it holds even when its peer is unreachable, and anti-entropy on reconnect merges whatever diverged. A two-node cluster is just two peers pointing at each other:
toml
[cluster]
peers = ["10.0.0.2:9179"]
peer_port = 9179
cluster_token = "shared-cluster-secret"Concurrent edits to the same project or team made on two simultaneously isolated nodes resolve last-writer-wins by
updated_atwhen they reconnect; the older edit is dropped. Distinct objects are never lost. See Clustering for the full merge semantics.