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=<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
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:
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. |
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.
| 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.