Environment variables
Look up environment variables, their defaults, and where each one takes effect.
These variables affect the Clarvis process, including the local interface and every project it opens. Set them in the environment that starts Clarvis, not in .clarvis/settings.json. This page also covers the portable installer; remote server deployment options are outside its scope.
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=<level> 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
A ceiling is the highest accepted value. Settings or agents that exceed it are rejected. A CLARVIS_DEFAULT_* variable provides a default only when the agent or settings.json does not define another value.
| 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:
CLARVIS_TOKEN_CEILING=400000000 \
CLARVIS_DEFAULT_TOTAL_TOKEN_LIMIT=180000000 \
CLARVIS_ITERATION_CEILING=400 \
clarvisCompaction
| 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. |
When a concurrency limit is reached, new operations may be skipped or refused, depending on the feature. Raising a limit does not change tool permissions, workspace trust, or sandbox rules.
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.
| 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 installer also has options for testing local artifacts during release preparation. They are not needed to install a published version and are not listed here. Use the installer for the version you chose.
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.