---
url: https://clusto.app/docs/configuration.md
description: >-
  Configure Clusto daemons and clients, inspect their storage, and manage
  projects, shells, session users, logging, and TLS.
---

# 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 --json
```

On 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](/migrating-from-hive#repair-or-finish-a-stuck-node).

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 --rollback
```

Rollback 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](/migrating-from-hive) 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 = 300
```

> Full-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](/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-ai
```

Authenticate 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 login
```

The 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 = 1700000000000
```

The 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](/chats#create-a-chat) and [Teams](/teams#ai-providers-teamagent)
for provider-specific runtime behavior.

#### GitHub (`[github]`)

The [GitHub view](/github) 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"
```

* `accounts` is **cluster-shared**: the whole list replicates to every node, and a
  node adopts a peer's copy when its `updated_at` is newer (whole-list
  last-writer-wins, so removing an account needs no tombstone).
* `tokens` is keyed by account id: a GitHub token exists only on the nodes of the
  account's host list (the host node, then its `standby_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, and `login` is the account
  the token authenticated as when it was saved.
* `pinned` repositories are listed first and always polled as active; `hidden`
  ones are left out of the view and never polled.

See [GitHub](/github) for the setup fields, [standby nodes](/github#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](/teams#model-catalog-and-tiers)). 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](/node-identity#pairing-codes). 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](/node-identity#unencrypted-connections) |
| `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](#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](/chats#choose-the-os-user-for-chats) and [Teams](/teams#which-os-user-a-team-runs-as) |
| `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](/chats#choose-a-workspace-optional) |
| `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](/chats#dedicated-workspace-replication) |
| `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](/factory#factory-machine) |
| `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](/teams) |
| `[update]` | Table | clusto.app | Self-update manifest URL, token, auto-check schedule, and remote flag fetching; see [Remote-URL Updates](/remote-updates) and [Feature Flags](/feature-flags) |
| `[knowledge]` | Table | enabled | Agent knowledge wiring and backups; see [Knowledge](/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](/agent-docs#sync-modes) |
| `[notes]` | Table | local vault | Notes vault location, owning `user`, and S3 sync; see [Notes](/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](/clustering#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](/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](/clusto-tunnel#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](/node-identity).

### Update and feature flag settings

Beyond the manifest URL, token and auto-check schedule (see
[Remote-URL Updates](/remote-updates)), `[update]` controls the remote feature
flag file described in [Feature Flags](/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](/remote-updates#moving-off-the-old-channels).

```toml
[update]
fetch_flags = true
flags_interval_secs = 900

[features]
"some.node_flag" = true
```

### Commands

`[[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 = true
```

Edit 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:

1. **No command sent** - the daemon uses the project's own `default_shell`
   (see below) when the request names a project, then `default_pty_shell`,
   falling back to `claude_bin`.
2. **A registry name or program path** - the matching enabled entry supplies the
   program and its `args`. Arguments sent with the request replace the entry's
   `args` rather than extending them.
3. **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 to `claude` is replaced
   by the configured `claude_bin`, so a bare `claude` always 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](/knowledge#mcp-tools) (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](/github#clone-a-repository-as-a-project) and
`clusto project clone` in the [CLI](/cli#clusto-project-manage-projects). 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](/clustering#cluster-configuration-in-settings)).

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](/factory#factory-machine).

### 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`](/cli#clusto-task-manage-scheduled-tasks), or the WebSocket task messages described in [Tasks](/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](/node-identity)). 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](/clusto-tunnel#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 live `wss://` 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.net` name whose cert and key sit at
  `<config dir>/tls/<name>.crt` and `.key`), the daemon re-runs `clusto cert` itself,
  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 ls
```

**Environment 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 ls
```

**App (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`](/cli) / the [web client](/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](/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](/clustering#peer-transport).

## 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`](/cli#clusto-profile-saved-connection-profiles)).

### 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_at` when they reconnect;
> the older edit is dropped. Distinct objects are never lost. See
> [Clustering](/clustering) for the full merge semantics.
