Skip to content

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 ​

VariableDefaultEffect
ENSEMBLE_LOGon0 disables file and ring logging. Any other value keeps logging on.
ENSEMBLE_LOG_LEVELinfoMinimum level: error, warn, info, debug, or trace. An invalid value falls back to info.
ENSEMBLE_LOG_DIR$XDG_STATE_HOME/ensemble/logsLog sink directory. When XDG_STATE_HOME is unset, the default is ~/.local/state/ensemble/logs.
ENSEMBLE_LOG_CONTENToff1 includes task and message text in logs. Privacy-sensitive; leave unset unless you need the text.
ENSEMBLE_LOG_STDERRoff1 mirrors log lines to stderr.
ENSEMBLE_DEBUG_CLONESoff1 exposes full-clone counts and timing on the diagnostic RPC.
ENSEMBLE_REDUCED_MOTIONoff1 or true freezes decorative motion.
ENSEMBLE_ASCIIoff1 or true uses ASCII chrome separators and marks. TERM=dumb has the same effect.
NO_COLORunsetPresence of any value, including the empty string, suppresses color and also enables reduced motion.
TERMinheriteddumb selects the ASCII chrome fallback. Other values are owned by the terminal.
XDG_STATE_HOME~/.local/stateBase 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_PASSWORDservice descriptor passwordBasic-auth password for the service RPCs used by doctor, data, backup, and the support bundle. It takes precedence over the descriptor password.

State paths ​

PathOwnerNotes
$XDG_STATE_HOME/ensemble/logsEnsembleDefault 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.jsonOpenCodeService descriptor read by the operator CLIs. --service-file overrides the path; --server overrides the URL.
~/.local/stateOpenCode and EnsembleFallback 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 variablePurpose
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_EXPECTExpected native-subagent behavior for the live probe.
ENSEMBLE_HOST_PROBE_EVENTSHost-probe event capture selection.
ENSEMBLE_NATIVE_HOST_FIXTUREModule path for the native-host fixture test.
OPENCODE_BIN, TMUX_BIN, NODE_BINExplicit executables for the live harness.

Next ​

Released under the MIT License.