# 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 [#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](/docs/build/config/environment-variables). 3. `~/.cluster/config.toml`. 4. Built-in defaults. Flags apply to a single run and are never written to `config.toml`: | Flag | Scope | Overrides | | --------------------- | -------------- | -------------------------------------------------------------------- | | `--model ` (`-m`) | `cluster exec` | `default_model` | | `--effort ` | `cluster exec` | `reasoning_effort` | | `--no-memory` | global | `memory_use` and `memory_generate`, plus explicit `/remember` writes | | `--trust-workspace` | global | Saved `[projects]` trust, for this process only | 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](/docs/build/interactive#slash-commands). There is no per-project config layer. Per-project state — saved [workspace trust](/docs/build/config/advanced#workspace-trust) and [instruction files](/docs/build/config/advanced#project-instructions) — is described in [Advanced configuration](/docs/build/config/advanced). ## The `cluster config` command [#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: ```bash cluster config show # print the most common settings and file locations cluster config get default_model cluster config set default_model ``` `cluster config get` accepts every key in the [reference](#key-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: ```bash cluster config set reasoning_effort "" ``` ## Common settings [#common-settings] ### Default model [#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: ```bash cluster models cluster config set default_model ``` ```toml 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 `, or switch mid-conversation with `/model `. To start against a self-hosted [Ollama server](/docs/build/ollama) instead, set `default_model_provider` to a provider you have declared under `[model_providers]` (see [Model providers](/docs/build/config/advanced#model-providers)). ### Reasoning effort [#reasoning-effort] Reasoning-capable models accept an effort hint — one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`: ```bash cluster config set reasoning_effort high ``` ```toml 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 `, or live with `/effort `. ### Service tier [#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](/docs/build/interactive#fast-mode)). ```toml service_tier = "fast" ``` ### Appearance [#appearance] ```toml 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 [#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: ```toml 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 [#what-the-model-sees] ```toml 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](/docs/build/config/advanced#project-instructions) for which files are discovered. ### Memory [#memory] ```toml [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](/docs/build/memory). ### Automatic updates [#automatic-updates] ```toml auto_update_enabled = true ``` Interactive sessions check for a newer release in the background and install it when they can. See [Updates](/docs/build/updates). ## Key reference [#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. | Key | Default | Purpose | | --------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `default_model` | `claude-opus-4-7` | Model used for new sessions | | `default_model_provider` | `cluster` | Provider used at startup — `cluster`, or the name of a configured [Ollama provider](/docs/build/config/advanced#model-providers) | | `reasoning_effort` | *(model default)* | Default reasoning effort | | `service_tier` | `standard` | `standard` or `fast` scheduling tier | | `term_bg` | `dark` | Force `light` or `dark` terminal appearance | | `syntax_theme` | *(adaptive default)* | Bundled or user-provided syntax theme name | | `auto_compact_enabled` | `true` | Auto-summarize context as it fills | | `auto_compact_threshold_tokens` | `160000` | Prompt-token count that triggers compaction | | `compact_keep_recent_user_tokens` | `20000` | Recent user text preserved verbatim when compacting | | `include_environment_context` | `true` | Share cwd, shell, date, and timezone with the model | | `include_project_instructions` | `true` | Send global and repository instruction files with each request | | `auto_update_enabled` | `true` | Background release check and install on interactive startup | | `memory_use` | `true` | Inject the memory overview and enable memory tools — `[memory] use_memories` | | `memory_generate` | `true` | Automatically extract memory from completed sessions — `[memory] generate_memories` | | `browser_enabled` | `true` | Built-in browser tool provider — `[browser] enabled` | | `computer_enabled` | `false` | Native `computer` desktop tool on supported sessions — `[computer] enabled` (see [Computer use](/docs/build/computer-use)) | | `computer_unattended` | `false` | Suppress per-process capture and control prompts — `[computer] unattended` | | `request_user_input_default_mode` | `false` | Allow the `request_user_input` clarification tool outside plan mode — `[tools] request_user_input.default_mode` | | `remote_control_at_startup` | `false` | Connect new sessions to [remote control](/docs/build/interactive#remote-control) automatically | | `remote_control_server_name` | *(hostname)* | Name this machine shows under in the remote session list | | `api_url` | `https://llm.clusterbase.dev` | Hosted agent gateway | | `search_api_url` | `https://search.clusterbase.ai` | Backend for the `web_search` / `web_fetch` tools | | `billing_api_url` | `https://gateway.clusterbase.ai` | Gateway serving the signed-in organization's billing plan | | `managed_agents_url` | `https://agents.clusterbase.dev` | Cloud host for [`/megaplan` and `/megareview`](/docs/build/cloud) | | `auth_issuer` | `https://accounts.clusterbase.ai` | Sign-in identity provider | | `auth_audience` | `agent-api` | OAuth audience | 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](/docs/build/config/advanced). ## Next steps [#next-steps] * **[Advanced configuration](/docs/build/config/advanced)** — model providers, MCP servers, skills, custom commands, workspace trust, and where state lives. * **[Environment variables](/docs/build/config/environment-variables)** — shell-scoped overrides and diagnostics. * **[Sample config.toml](/docs/build/config/sample)** — a complete annotated file to copy from.