Config basics

Cluster Build keeps its settings in one file, ~/.cluster/config.toml. The file is created the first time you change a setting; until then every value falls back to a built-in default. Interactive sessions, cluster exec, and the app-server all read the same file.

Precedence

Cluster Build resolves each setting in this order (highest precedence first):

1. Command-line flags for the current run, such as cluster exec --model.
2. Environment variables for the current shell — see Environment variables.
3. ~/.cluster/config.toml.
4. Built-in defaults.

Flags apply to a single run and are never written to config.toml:

Inside a session, /model, /effort, /fast, /appearance, /theme, and /remote change the live value; the ones that map to a config key also persist it. See Slash commands.

There is no per-project config layer. Per-project state — saved workspace trust and instruction files — is described in Advanced configuration.

The cluster config command

You can edit config.toml by hand, but cluster config validates values and writes the file for you, including keys that live in a nested table:

cluster config show                       # print the most common settings and file locations
cluster config get default_model
cluster config set default_model <model-id>

cluster config get accepts every key in the reference below. cluster config set rejects unknown keys and invalid values (a non-URL for api_url, a non-boolean for a switch, an unsupported reasoning effort) and leaves the file unchanged. Writes take a cross-process lock and replace the file atomically, so two commands changing different keys at the same time do not overwrite each other.

Passing an empty string to an optional key clears it:

cluster config set reasoning_effort ""

Common settings

Default model

Cluster Build runs against Clusterbase's hosted gateway, which serves Claude, GPT, and other frontier models. List what's available, then set a default:

cluster models
cluster config set default_model <model-id>

default_model = "claude-opus-4-7"

Prefer cluster models over a model id copied from elsewhere — the catalog changes over time. Override the default for one run with cluster exec --model <id>, or switch mid-conversation with /model <id>.

To start against a self-hosted Ollama server instead, set default_model_provider to a provider you have declared under [model_providers] (see Model providers).

Reasoning effort

Reasoning-capable models accept an effort hint — one of none, minimal, low, medium, high, xhigh, max:

cluster config set reasoning_effort high

reasoning_effort = "high"

Leave it unset to use each model's own default. Cluster Build validates the level against the selected model's advertised reasoning_levels before sending a request: an unsupported level is rejected locally with the allowed levels listed. Switching models with /model carries the current effort over when the new model supports it and otherwise falls back to that model's default. Override per run with cluster exec --effort <level>, or live with /effort <level>.

Service tier

service_tier picks the gateway scheduling tier for foreground requests: standard (default) or fast. Fast responds sooner and is billed at the premium rate on models that support it (see Fast mode).

service_tier = "fast"

Appearance

term_bg = "light"          # or "dark" (default); `/appearance` writes this
syntax_theme = "catppuccin-latte"   # `/theme` writes this; user themes live in ~/.cluster/themes/

CLUSTER_TERM_BG overrides term_bg for a single run.

Context compaction

As a conversation grows, Cluster Build summarizes older turns to free up room. /compact triggers it manually; these keys control the automatic path:

auto_compact_enabled = true
auto_compact_threshold_tokens = 160000   # prompt-token count that triggers compaction
compact_keep_recent_user_tokens = 20000  # recent user text kept verbatim after the summary

What the model sees

include_environment_context = true    # cwd, shell, date, and timezone
include_project_instructions = true   # ~/.cluster/AGENTS.md plus AGENTS.md / CLAUDE.md in the repo

Both blocks are sent as non-persisted context on every request; they are never written into the saved session. See Project instructions for which files are discovered.

Memory

[memory]
use_memories = true        # inject the memory overview and enable memory tools
generate_memories = true   # extract and consolidate memory from finished sessions

cluster config set memory_use false and cluster config set memory_generate false write these keys. --no-memory disables everything for one process without touching the file. See Cross-session memory.

Automatic updates

auto_update_enabled = true

Interactive sessions check for a newer release in the background and install it when they can. See Updates.

Key reference

Every key accepted by cluster config get and cluster config set. Keys marked with a table name are stored nested in config.toml but addressed by the flat name on the command line.

Tables that hold structured settings — [model_providers.*], [mcp.servers.*], [skills], and [projects.*] — are edited in the file directly or through their own commands. They are covered in Advanced configuration.

Next steps

• Advanced configuration — model providers, MCP servers, skills, custom commands, workspace trust, and where state lives.
• Environment variables — shell-scoped overrides and diagnostics.
• Sample config.toml — a complete annotated file to copy from.