Environment
These variables change Ensemble's local behavior. None of them sends data off the machine and none is required for a normal install.
Product variables
| Variable | Default | Effect |
|---|---|---|
ENSEMBLE_LOG | on | 0 disables file and ring logging. Any other value keeps logging on. |
ENSEMBLE_LOG_LEVEL | info | Minimum level: error, warn, info, debug, or trace. An invalid value falls back to info. |
ENSEMBLE_LOG_DIR | $XDG_STATE_HOME/ensemble/logs | Log sink directory. When XDG_STATE_HOME is unset, the default is ~/.local/state/ensemble/logs. |
ENSEMBLE_LOG_CONTENT | off | 1 includes task and message text in logs. Privacy-sensitive; leave unset unless you need the text. |
ENSEMBLE_LOG_STDERR | off | 1 mirrors log lines to stderr. |
ENSEMBLE_DEBUG_CLONES | off | 1 exposes full-clone counts and timing on the diagnostic RPC. |
ENSEMBLE_REDUCED_MOTION | off | 1 or true freezes decorative motion. |
ENSEMBLE_ASCII | off | 1 or true uses ASCII chrome separators and marks. TERM=dumb has the same effect. |
NO_COLOR | unset | Presence of any value, including the empty string, suppresses color and also enables reduced motion. |
TERM | inherited | dumb selects the ASCII chrome fallback. Other values are owned by the terminal. |
XDG_STATE_HOME | ~/.local/state | Base for Ensemble logs and the OpenCode service descriptor. Ensemble does not read XDG_CONFIG_HOME, XDG_DATA_HOME, or XDG_CACHE_HOME for its own state. |
OPENCODE_PASSWORD | service descriptor password | Basic-auth password for the service RPCs used by doctor, data, backup, and the support bundle. It takes precedence over the descriptor password. |
State paths
| Path | Owner | Notes |
|---|---|---|
$XDG_STATE_HOME/ensemble/logs | Ensemble | Default log directory, or ENSEMBLE_LOG_DIR. Files are owner-only in an owner-only directory; default retention is 7 days, 5 rotated files per role/prefix, and 10 MiB per file. |
$XDG_STATE_HOME/opencode/service.json | OpenCode | Service descriptor read by the operator CLIs. --service-file overrides the path; --server overrides the URL. |
~/.local/state | OpenCode and Ensemble | Fallback base when XDG_STATE_HOME is unset. |
XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_CACHE_HOME are set by the live test harness. Ensemble does not use them for its own state, so do not document them as product configuration.
Support bundle redaction
The support bundle removes the values of OPENCODE_PASSWORD, GITHUB_TOKEN, and NPM_TOKEN from every collected file. The last two are redaction inputs, not Ensemble configuration. There is no telemetry upload.
Test-harness variables
These variables belong to the repository's live, fake, benchmark, and soak harnesses. They are not user configuration and are unsupported for installed packages.
| Prefix or variable | Purpose |
|---|---|
ENSEMBLE_LIVE_* | Live-suite selection, expectations, timeouts, artifacts, and TUI size. |
ENSEMBLE_LATENCY_* | Latency probe profile, samples, server, workspace, and output. |
ENSEMBLE_PROBE_* | Host-probe artifacts, output, validation, and write controls. |
ENSEMBLE_FAKE_* | Deterministic fake-host delays, handoff directory, and initial timing. |
ENSEMBLE_SOAK_* | Soak duration, agents, workspaces, burst, sample interval, RSS ceilings, and output. |
ENSEMBLE_V6_* | Legacy size-matrix selection and load-skip controls. |
ENSEMBLE_SUBAGENT_EXPECT | Expected native-subagent behavior for the live probe. |
ENSEMBLE_HOST_PROBE_EVENTS | Host-probe event capture selection. |
ENSEMBLE_NATIVE_HOST_FIXTURE | Module path for the native-host fixture test. |
OPENCODE_BIN, TMUX_BIN, NODE_BIN | Explicit executables for the live harness. |
Next
- Configuration: the stored settings these variables do not change.
- Files and storage: log and state layout.