Environment variables

Environment variables Cluster Build reads — one-run overrides for config.toml values, the installer's INSTALL_DIR, editor and proxy settings, and RUST_LOG for diagnostics.

Cluster Build uses config.toml for durable settings. Use environment variables for shell-scoped overrides, installer behavior, and diagnostics. An environment variable always wins over the matching config.toml key for the process that sees it, and never changes the file.

This page lists the public variables the CLI reads directly. It does not list the variable names you choose yourself for MCP servers — those are declared in config.toml with env_vars, bearer_token_env_var, and env_http_headers, and Cluster Build reads whatever names you put there. See stdio servers and streamable HTTP servers.

Overrides

Variable	Overrides	Description
`CLUSTER_TERM_BG`	`term_bg`	`light` or `dark` terminal appearance for this run.
`CLUSTER_REDUCED_MOTION`	—	Set to any value to disable the spinner animation in the TUI.
`SEARCH_API_V2_URL`	`search_api_url`	Backend for the `web_search` / `web_fetch` tools for this run.

CLUSTER_TERM_BG=light cluster

Installer

These apply to the install script served from https://assets.cluster.app/serve/cstatic-assets/releases/cli/install.sh.

Variable	Default	Description
`INSTALL_DIR`	first user-writable bin directory on `PATH` (typically `~/.local/bin`)	Where the `cluster` binary is installed. A directory that needs elevated permissions falls back to `sudo`. Keep it user-writable so the CLI can update itself.

curl -fsSL https://assets.cluster.app/serve/cstatic-assets/releases/cli/install.sh | INSTALL_DIR=~/bin sh

Editor and shell

Variable	Used by	Description
`VISUAL`, `EDITOR`	External editor in the TUI	Checked in that order for the `Ctrl-O` external editor, then `nvim`, `vim`, `vi`, `hx`, `nano`. The program must be on `PATH`.
`SHELL`	Environment context, stdio MCP servers	Reported to the model when `include_environment_context` is on, and forwarded to stdio MCP servers. The shell tool itself always runs commands through `sh`.

Network

Variable	Description
`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` (and lowercase forms)	Standard proxy settings, honored by every HTTPS client in the CLI — gateway, search, updates, and streamable-HTTP MCP servers.

cluster doctor reports which proxy variables are set, with values redacted.

Diagnostics

Variable	Description
`RUST_LOG`	Standard `tracing` filter for the rolling log file and, for one-shot commands, stderr. When unset, the CLI logs at `info` for its own crates, or `debug` with `--verbose`.

Logs are written to ~/.cluster/logs/ (daily rotation, thirty files kept). Interactive sessions never print log lines to the terminal, so the file is the place to look:

RUST_LOG=build_core=debug,build_cli=debug cluster
tail -F ~/.cluster/logs/cluster.log.$(date +%F)

cluster doctor includes every CLUSTER_* variable and RUST_LOG in its report, with secret-looking values redacted. See Diagnostics.

Next steps

Config basics — the settings these variables override.
Advanced configuration — MCP servers and how they receive credentials from the environment.