# Environment variables



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](/docs/build/config/advanced#stdio-servers) and
[streamable HTTP servers](/docs/build/config/advanced#streamable-http-servers).

## Overrides [#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. |

```bash
CLUSTER_TERM_BG=light cluster
```

## Installer [#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. |

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

## Editor and shell [#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 [#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 [#diagnostics]

| Variable   | Description                                                                                                                                                                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RUST_LOG` | Standard [`tracing` filter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) 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:

```bash
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](/docs/build/diagnostics).

## Next steps [#next-steps]

* **[Config basics](/docs/build/config/basic)** — the settings these
  variables override.
* **[Advanced configuration](/docs/build/config/advanced#mcp-servers)** — MCP
  servers and how they receive credentials from the environment.