# Environment variables > Configure Clarvis paths, launcher behavior, runtime ceilings, diagnostics, extension admission, > provider transport, MCP pooling, and retention without hiding which values are process-wide. This reference covers the shared engine and kernel, the local TUI, and the portable installer. Server-host deployment variables are a separate host surface. Environment variables apply to the Clarvis process and every workspace kernel it creates. They are host policy, not workspace settings: a repository should not rely on changing them through `.clarvis/settings.json`. For boolean variables, unset means the documented default. The strings `false`, `0`, `no`, `off`, and an empty value mean false, case-insensitively; any other string means true. Invalid numbers, enums, or a default above its matching ceiling stop startup with an `Invalid environment configuration` error rather than being guessed. ## Paths and the TUI | Variable | Default | Effect | | -------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `CLARVIS_HOME` | `~/.clarvis` | Replaces the global authored and state root. Use the same value when backing up, clearing, or diagnosing that installation. | | `CLARVIS_WORKSPACE_ROOT` | Current directory | Overrides the workspace root for an embedding or launcher. Ordinary users should start `clarvis` from the intended project instead. | | `CLARVIS_OWNER` | Host-selected owner | Partitions owner-scoped state when one host serves more than one logical operator. | | `CLARVIS_DEFAULT_MODEL` | Unset | Last-resort `provider/model` when neither settings nor the selected agent supplies one. Prefer `/model` for normal interactive use. | | `CLARVIS_CODE_DEBUG` | Off | Opens bounded TUI diagnostics. A level (`error`, `warn`, `info`, or `debug`) both enables and tunes it; another true value uses `debug`. | | `CLARVIS_CODE_DEBUG_LEVEL` | `debug` | Tunes diagnostics enabled through `CLARVIS_CODE_DEBUG`; `--debug=` has higher precedence. | | `CLARVIS_TUI_RSS_LIMIT_MB` | `2048` | Interactive-process memory fuse in MiB. `0` disables it; positive values have a 512 MiB floor. | ## Run ceilings and defaults Ceilings reject a larger setting or agent value. A `CLARVIS_DEFAULT_*` variable supplies a fallback only when a nearer agent or `settings.json` value does not replace it. | Variable | Default | Effect | | ------------------------------------------- | ----------: | ------------------------------------------------------------------------------------- | | `CLARVIS_TOKEN_CEILING` | `200000000` | Maximum accepted run token limit. | | `CLARVIS_ITERATION_CEILING` | `200` | Maximum accepted agent iteration limit. | | `CLARVIS_TIMEOUT_CEILING_MS` | `600000` | Maximum accepted inactivity or model-call timeout. | | `CLARVIS_ESCALATION_CEILING` | `20` | Maximum accepted budget escalation count. | | `CLARVIS_RETRY_CEILING` | `10` | Maximum accepted provider retry count. | | `CLARVIS_RETRY_AFTER_CEILING_MS` | `300000` | Maximum accepted provider-requested retry delay. | | `CLARVIS_DEFAULT_TOTAL_TOKEN_LIMIT` | `160000000` | Fallback cumulative input-plus-output token budget for one run. | | `CLARVIS_DEFAULT_TIMEOUT_MS` | `300000` | Fallback inactivity timeout. | | `CLARVIS_DEFAULT_ON_EXCEED` | `escalate` | Fallback boundary behavior: `stop` or `escalate`. | | `CLARVIS_DEFAULT_MAX_ESCALATIONS` | `5` | Fallback budget escalation allowance. | | `CLARVIS_DEFAULT_ELICIT_WAIT_MS` | `1800000` | Maximum wait for an interactive answer. | | `CLARVIS_DEFAULT_ITERATION_LIMIT` | `200` | Fallback lead-agent iteration limit. | | `CLARVIS_DEFAULT_CONTEXT_WINDOW_TOKENS` | `128000` | Context-window fallback when the model catalog has no value. | | `CLARVIS_DEFAULT_STAGNATION_THRESHOLD` | `3` | Repeated non-progress threshold that trips the convergence guard. | | `CLARVIS_DEFAULT_STAGNATION_SOFT_THRESHOLD` | `2` | Warning threshold before the hard stagnation boundary; `0` disables the warning tier. | | `CLARVIS_GUARD_MAX_ESCALATIONS` | `2` | Human overrides allowed after hard convergence-guard trips; `0` disables them. | | `CLARVIS_DEFAULT_CALL_TIMEOUT_MS` | `180000` | Streaming inactivity window; absolute bound until observable progress begins. | | `CLARVIS_DEFAULT_REASONING_SUMMARY` | `off` | Fallback reasoning summary: `off`, `auto`, or `detailed`. | | `CLARVIS_DEFAULT_REASONING_EFFORT` | Unset | Fallback effort: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. | | `CLARVIS_DEFAULT_MAX_RETRIES` | `3` | Fallback retries for a model call. | | `CLARVIS_DEFAULT_MAX_RETRY_AFTER_MS` | `60000` | Fallback maximum accepted retry delay. | | `CLARVIS_DEFAULT_FORCE_TOOL_ON_NUDGE` | On | Requires a tool call after the loop nudges a stalled agent. | | `CLARVIS_DEFAULT_PENDING_TASK_NUDGES` | `3` | Consecutive plan-task nudges before finalization stops asking. | | `CLARVIS_STREAM` | On | Enables model streaming where the provider supports it. | Every default paired with a ceiling must remain at or below that ceiling. For example: ```bash CLARVIS_TOKEN_CEILING=400000000 \ CLARVIS_DEFAULT_TOTAL_TOKEN_LIMIT=180000000 \ CLARVIS_ITERATION_CEILING=400 \ clarvis ``` ## Compaction | Variable | Default | Effect | | --------------------------------------------------- | -------: | --------------------------------------------------------------------------------------- | | `CLARVIS_DEFAULT_COMPACTION_ENABLED` | On | Enables automatic context compaction. | | `CLARVIS_DEFAULT_COMPACTION_CONTEXT_FRACTION` | `0.8` | Context occupancy that makes compaction eligible. Must be greater than 0 and at most 1. | | `CLARVIS_DEFAULT_COMPACTION_TARGET_FRACTION` | `0.5` | Target occupancy after compaction. Must be greater than 0 and at most 1. | | `CLARVIS_DEFAULT_COMPACTION_MAX_RESULT_CHARS` | Unset | Optional maximum characters accepted from a compaction result. | | `CLARVIS_DEFAULT_COMPACTION_PRESERVE_RECENT_TOKENS` | Unset | Optional recent-token tail kept outside the summary. | | `CLARVIS_COMPACTION_LLM_TIMEOUT_MS` | `120000` | Wall limit for the compaction model call. | ## Tools, capabilities, and concurrency | Variable | Default | Effect | | ------------------------------------------------------ | ------: | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLARVIS_AGENT_TOOLS_ENABLED` | On | Registers agent-management tools. | | `CLARVIS_AGENT_TOOLS_CONFINE` | On | Confines those tools to the current run and workspace policy. | | `CLARVIS_AGENT_TOOLS_MAX_GRANT` | `edit` | Host-schema ceiling: `none`, `read`, `edit`, or `exec`. The interactive TUI defaults this to `exec` before kernel creation unless explicitly set. | | `CLARVIS_SKILLS_ENABLED` | On | Registers skill discovery and `load_skill`. | | `CLARVIS_HOOKS_ENABLED` | On | Registers lifecycle hooks. | | `CLARVIS_MEMORY_TOOL_CALL_LIMIT` | `12` | Per-run budget for memory read tools; memory writes are not counted here. | | `CLARVIS_MEMORY_LOCK_WARN_MS` | `5000` | Emits a warning when a memory-tree lock is held longer than this. | | `CLARVIS_CAPABILITY_SETUP_TIMEOUT_MS` | `5000` | Per-capability activation/seed wall limit; hard maximum 60 seconds. | | `CLARVIS_CAPABILITY_RUN_END_TIMEOUT_MS` | `2000` | Per-capability finalization wall limit after the answer is decided. | | `CLARVIS_MAX_CONCURRENT_EXTENSION_CALLS` | `32` | Host-wide foreground extension-call ceiling. | | `CLARVIS_MAX_CONCURRENT_EXTENSION_RUN_END_CALLS` | `8` | Host-wide run-end extension-call ceiling. | | `CLARVIS_MAX_CONCURRENT_EXTENSION_CALLS_PER_OPERATION` | `4` | Maximum concurrent extension calls owned by one operation. | | `CLARVIS_MAX_PARALLEL_SUBAGENTS` | `4` | Maximum sub-agents admitted in parallel. | | `CLARVIS_MAX_CONCURRENT_MODEL_CALLS` | `4` | Host-wide physical model-call ceiling. | | `CLARVIS_MAX_QUEUED_MODEL_CALLS` | `8` | Maximum model calls waiting behind that ceiling. | | `CLARVIS_RUN_ABORT_SETTLE_MS` | `2000` | Grace for an entire cancelled or timed-out run to unwind. | | `CLARVIS_MODEL_ABORT_SETTLE_MS` | `250` | Shorter quarantine grace for one physical provider transport. | Saturation skips or refuses new bounded work according to the owning capability; raising a number does not change tool grants, workspace trust, or sandbox policy. ## Logging and provider transport | Variable | Default | Effect | | -------------------------------------- | ---------: | ----------------------------------------------------------------------------------------------------------------------- | | `CLARVIS_LOG_LEVEL` | `info` | Global structured-log floor: `debug`, `info`, `warn`, `error`, or `silent`. | | `CLARVIS_LOG` | Unset | Comma-separated component overrides such as `paths.lease=debug,mcp=debug,llm=warn`. Unknown component names are no-ops. | | `CLARVIS_LOG_AUDIT` | On | Keeps authentication and command-guard audit records independent of the ordinary log floor. | | `CLARVIS_STREAM_DEBUG` | Unset | JSONL file path for low-level streaming counters. Leave unset outside focused diagnostics. | | `CLARVIS_PROVIDER_RETRY_BASE_MS` | `1000` | Initial provider retry backoff. | | `CLARVIS_PROVIDER_RETRY_MAX_MS` | `30000` | Maximum provider retry backoff. | | `CLARVIS_PROVIDER_MAX_RESPONSE_BYTES` | `33554432` | Maximum complete provider response (32 MiB). | | `CLARVIS_PROVIDER_MAX_SSE_EVENT_BYTES` | `4194304` | Maximum provider SSE event (4 MiB). | Use `--debug` or `/debug` for the normal bounded diagnostic workflow. Log environment variables are for host operators and do not replace redaction or the audit channel. ## MCP host limits Per-server fields such as `startup_timeout_sec`, `tool_timeout_sec`, `env_vars`, `bearer_token_env_var`, and tool allow/deny lists belong in `mcpServers`, not in this table. See [MCP servers](/guide/mcp-servers). | Variable | Default | Effect | | -------------------------------------- | ---------: | ----------------------------------------------------------------------------------------------------- | | `CLARVIS_MCP_SERVER_STDERR` | `log` | Handles stdio-server stderr as `off`, structured `log`, or raw `inherit`. Avoid `inherit` in the TUI. | | `CLARVIS_MCP_SERVER_STDERR_MAX_BYTES` | `65536` | Forwarded stderr ceiling per connection. | | `CLARVIS_MCP_CONNECT_TIMEOUT_MS` | `10000` | Default connection/startup timeout. | | `CLARVIS_MCP_TOOL_CALL_TIMEOUT_MS` | `600000` | Default MCP tool-call timeout. | | `CLARVIS_MCP_POOL_IDLE_TTL_MS` | `60000` | Idle lifetime before a pooled connection is closed. | | `CLARVIS_MCP_STDIO_MAX_FRAME_BYTES` | `16777216` | Maximum stdio protocol frame (16 MiB). | | `CLARVIS_MCP_HTTP_MAX_RESPONSE_BYTES` | `16777216` | Maximum remote response (16 MiB). | | `CLARVIS_MCP_HTTP_MAX_SSE_EVENT_BYTES` | `4194304` | Maximum remote SSE event (4 MiB). | | `CLARVIS_MCP_MAX_SERVERS_PER_RUN` | `16` | Per-run server ceiling; it must not exceed `CLARVIS_MCP_MAX_CONNECTIONS`. | | `CLARVIS_MCP_MAX_CONNECTIONS` | `32` | Host-wide open-connection ceiling. | | `CLARVIS_MCP_MAX_PARALLEL_CONNECTS` | `4` | Concurrent connection-attempt ceiling. | | `CLARVIS_MCP_MAX_IDLE_CONNECTIONS` | `8` | Idle connections retained in the pool. | | `CLARVIS_MCP_TIMEOUT_STREAK_THRESHOLD` | `3` | Consecutive timeouts before a connection is treated as unhealthy. | | `CLARVIS_MCP_HEALTH_PING_INTERVAL_MS` | `30000` | Health-ping interval; `0` disables periodic pings. | | `CLARVIS_MCP_RESOURCES` | On | Host-wide resource-tool support. A server can still opt out with `resources: false`. | | `CLARVIS_MCP_POOL_SHARING` | `owner` | Pool isolation: `owner` or `workspace`. | ## Trace retention | Variable | Default | Effect | | ----------------------------------- | --------: | ---------------------------------------------------------------------------- | | `CLARVIS_TRACE_TTL_DAYS` | `30` | Age after which traces are eligible for cleanup; `0` disables trace cleanup. | | `CLARVIS_TRACE_CLEANUP_INTERVAL_MS` | `3600000` | Background cleanup cadence. | | `CLARVIS_TRACE_CLEANUP_BATCH_SIZE` | `1000` | Maximum records handled by one cleanup batch. | ## Portable installer variables These variables configure one managed installation. Reuse the same path overrides when uninstalling. | Variable | Platform | Default | Effect | | ---------------------- | -------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `CLARVIS_INSTALL_ROOT` | All | POSIX: `${XDG_DATA_HOME:-$HOME/.local/share}/clarvis`; Windows: `%LOCALAPPDATA%\Clarvis` | Managed versions, activation marker, and installation metadata. The generated launcher carries the selected root. | | `CLARVIS_BIN_DIR` | POSIX | `${XDG_BIN_HOME:-$HOME/.local/bin}` | Directory containing the managed `clarvis` launcher. | | `CLARVIS_SKIP_PATH` | Windows | Off | Set to `1` to keep the installer or uninstaller from changing the user `PATH`. | The source-tree installer also contains release-engineering overrides for local artifact smoke. They are not ordinary end-user configuration and are intentionally omitted here; use the immutable installer from the exact published tag. ## Variables passed to hooks and plugins Hook variables are outputs from Clarvis, not startup configuration. Every hook receives `CLARVIS_HOOK_PROTOCOL`, `CLARVIS_HOOK_EVENT`, `CLARVIS_HOOK_GATE`, and `CLARVIS_HOOK_TIMEOUT_MS`; tool events also receive `CLARVIS_HOOK_TOOL` and, for a namespaced MCP tool, `CLARVIS_HOOK_TOOL_FULL_NAME`. A plugin hook additionally receives `PLUGIN_ROOT` and `PLUGIN_DATA` plus the compatibility aliases `CODEX_PLUGIN_ROOT` and `CODEX_PLUGIN_DATA`. Those paths carry no credentials. Clarvis still filters provider credentials and secret-shaped variables before starting a hook, but a hook is an ordinary host process rather than a sandbox. ## See also - [Configuration](/reference/configuration) - [Installation and downloads](/installation) - [MCP servers](/guide/mcp-servers) - [Hooks](/guide/hooks) - [Security](/operations/security) --- [Canonical HTML](https://clarvis.dev/reference/environment-variables) [Documentation index](https://clarvis.dev/llms.txt)