Feature Flags

A release flag lets Clusto ship new or risky behavior in a build while keeping it switched off until it has been proven. The old behavior stays in the same binary, so a flag can be turned off again without a new release. Bug fixes and small changes ship without a flag.

Flags replace the old pre-release channel. There is one release track, and risky changes ship behind a flag instead of an unstable build. Early access (below) is what the old unstable channel became: a cluster that wants new behavior first turns it on in Settings > Labs.

Flags are not a compatibility layer: every node, client and the CLI still run the same version and speak the same protocol. A flag only decides which behavior runs.

How a flag is resolved

Each flag resolves to on or off. The first layer that has an opinion wins, highest first:

1. Node override - the [features] table in the node's config.toml. Ignored for cluster-scope flags, so nodes cannot disagree on purpose.
2. Cluster override - set per flag in Settings > Labs.
3. Remote kill-switch - a flag set to off in the published flags.json.
4. Early access - when the cluster has it on, every remaining flag is on.
5. Remote rollout - the other states in flags.json (see below).
6. Built-in default - the default shipped in the build.

Remote states

A flag in flags.json is in one of these states:

State	Meaning
off	Off for everyone, early access included (the kill-switch)
beta	Off, except for clusters with early access turned on
rollout with a percent	On for that share of installs
on	On for everyone

A rollout is bucketed locally: the node hashes its cluster token with the flag id and takes it modulo 100, so every node of one cluster lands in the same bucket. An unclustered node uses a random install id generated once and stored in its data directory. Nothing identifying leaves the machine; the node only downloads the file. Rotating the cluster token reshuffles the buckets.

Settings > Labs

Settings > Labs is the app's view of the flags for the connected cluster:

• Early access - a toggle. When on, every flag resolves to on for this cluster, whatever its built-in default or remote rollout, unless a per-flag override forces it off or the remote file switches it off.
• Per-flag override - each flag has a Default / On / Off selector. Default follows the remote rollout and built-in default; On and Off force the flag for the whole cluster.

The settings are shared by every node of the cluster. The last write wins, and a node that was offline during a change picks it up when it reconnects.

A node whose config still had [update] channel = "unstable" is migrated once on start: early access is turned on for the cluster (only if Labs settings were never set) and the key is removed from config.toml. See Remote-URL Updates.

Both are also in the F1 command palette: Open Labs settings and Turn on early access / Turn off early access.

Current flags

Flag	What it controls	Default
plugins.user	User plugins: the Plugins section in Settings, sidebar views, hooks, agent tools, palette commands and the clusto plugin commands (free on every plan)	off
agent_docs.sync	Automatic Agent Docs sync of user-scope instructions, skills, subagents and commands, with the per-node two-way, receive-only or manual mode. Off, items move only when you send and apply them	off
github.view	The GitHub view	off
azure_devops.view	The Azure DevOps view	off
time.tracking	Time tracking: the Time view at /time, the running-timer pill and the Time F1 commands (free on every plan) (cluster scope)	off
gitlab.accounts	GitLab accounts: the Settings -> GitLab tab	off
notes.multi_vault	Notes: the vault switcher, creating more vaults (a second one needs Pro, Team or a trial) and the per-vault Kept on node checklist. Off shows the single first vault as before (app scope)	off
telemetry.usage	Opt-in usage data: the consent prompt, Settings > Privacy and event upload	off (switched on remotely in flags.json)
security.session_credentials	Limited per-session credentials for sessions that run as a non-root account, instead of the node admin token (node scope)	off
terminal.truecolor	Starting new terminal sessions with COLORTERM=truecolor, so tools that detect color depth draw 24-bit color (node scope)	off
transport.refuse_lan_plaintext	Refusing credentials over unencrypted connections from networks other than loopback, Tailscale and [transport] plaintext_networks; off only warns (see Node Identity & Pairing) (node scope)	off (switched on remotely once apps have updated)

Remote flags file

Clusto publishes flags.json next to the update manifest, under the same base URL and bearer token ([update].manifest_url and token; see Remote-URL Updates). A node fetches it on its own schedule, independent of the update auto-check:

• It polls every flags_interval_secs (default 900, 15 minutes) with a conditional request, so an unchanged file costs one small 304 response.
• The last good copy is cached in the node's data directory and used while the node is offline. A node with no cache yet uses the built-in defaults.
• A malformed file is ignored: the node keeps the last good set and logs a warning.
• Nodes fetch independently, so a cluster-scope flag can differ between nodes for up to one interval.

Set fetch_flags = false in [update] to stop fetching. That removes the remote kill-switch: only built-in defaults and your overrides apply, and a previously cached copy is not used either.

A self-hosted mirror must copy flags.json along with the manifest, or its nodes run on built-in defaults. See Configuration for the settings.

Node override example

[features]
"github.view" = true

Use it to try a flag on one node. It does not apply to cluster-scope flags.

Publishing flag changes (operators)

Operators who run the distribution use clusto.ps1:

pwsh ./scripts/clusto.ps1 flags                          # list flags and their remote state
pwsh ./scripts/clusto.ps1 flags set <id> off|beta|on     # set a state
pwsh ./scripts/clusto.ps1 flags set <id> rollout 25      # roll out to 25%
pwsh ./scripts/clusto.ps1 flags unset <id>               # drop the remote entry

The command validates the id against the flags in the build, shows the change, and asks before publishing it to the distribution. Add -Force to skip the prompt. Nodes pick up a change within flags_interval_secs, so flags set <id> off is the kill-switch for a misbehaving flag.

A typical rollout: ship with the flag off, turn it on for a dev cluster in Labs, move it to beta, then rollout 10, 50 and 100, and finally make it the built-in default in a release. The flag and the old behavior are removed in a later release.