Environment Variables

Every KANNA_* env var Kanna reads, auto-extracted from source. These are tuning knobs — none of them is needed for a normal install.

Variable	Default	Description
`KANNA_BACKGROUND_TASK_MAX_WAKES`	`3`	How many times a background task may wake its chat after the keep-alive deadline passes before Kanna stops re-waking it.
`KANNA_CLAUDE_DRIVER`	`sdk`	Claude driver. Leave unset. "sdk" runs the Claude Agent SDK and is the supported mode; "pty" is a legacy path that drives the claude CLI under a pseudo-terminal, kept only for compatibility.
`KANNA_CLAUDE_SESSION_IDLE_MS`	`600000`	Idle window before a resident Claude session is reaped (10 min).
`KANNA_CLAUDE_SESSION_MAX_RESIDENT`	`4`	Max simultaneously resident Claude sessions before the least-recently-used is reaped.
`KANNA_CLAUDE_SESSION_SWEEP_INTERVAL_MS`	`60000`	How often the resident-session reaper sweeps for idle sessions.
`KANNA_CRON_CONFIRM`	`enabled`	Set to "disabled" to stop the host from escalating a typed /cron arm to a model review turn. When enabled, the model presents the full job config and asks the user to confirm, change, or disarm. Only fires on the typed path — arm_cron already confirms in-turn.
`KANNA_CRON_REPAIR`	`enabled`	Set to "disabled" to stop handing an invalid /cron line to the agent for repair. It only ever fires where Kanna has no corrected command of its own; the validate_cron / arm_cron tools stay registered either way.
`KANNA_DISABLE_SELF_UPDATE`	`0`	Set to "1" to disable the in-app self-update path.
`KANNA_HEAP_SNAPSHOT`	`enabled`	Set to "disabled" to stop SIGUSR2 from writing a V8 heap snapshot under the data dir. `kill -USR2 <pid>` is how you find what is holding memory on a live process.
`KANNA_IMPORT_FOLLOW_ACTIVE_WINDOW_MS`	`600000`	A single-session import only auto-arms live-tailing when the source file mtime is within this window of "now".
`KANNA_IMPORT_FOLLOW_IDLE_MS`	`600000`	The live-tail registry stops following a session after this long with no source file growth.
`KANNA_IMPORT_FOLLOW_POLL_MS`	`2000`	Stat-poll tick interval driving the single-session-import live-tail FollowedSessionRegistry.
`KANNA_LOG_ANALYTICS`	`0`	Set to "1" to log analytics payloads to stderr. Debugging aid.
`KANNA_LOG_CLAUDE_STEER`	`0`	Set to "1" to log mid-turn steering messages sent to Claude. Debugging aid.
`KANNA_MCP_TOOL_CALLBACKS`	`0`	Set to "1" to route AskUserQuestion / ExitPlanMode / built-in shims through the durable approval protocol.
`KANNA_MEMLOG_MS`	`60000`	Interval between "[kanna/mem] rss=…" process-memory log lines. Set to 0 to disable.
`KANNA_MERMAID_GUARD`	`enabled`	Set to "disabled" to stop the end-of-turn check that asks the model to fix a mermaid diagram that would not render. The validate_mermaid tool stays registered either way.
`KANNA_OPENROUTER_FIRST_ENTRY_TIMEOUT_MS`	`120000`	Fail-close timeout for an OpenRouter turn whose SDK stream stalls before the first transcript entry.
`KANNA_OTEL`	`(unset)`	Overrides the Settings telemetry toggle: "disabled" hard-disables export, "enabled" turns it on even when the setting is off. Unset means the setting decides.
`KANNA_OTEL_METRIC_INTERVAL_MS`	`15000`	How often metrics are exported to the OTLP endpoint.
`KANNA_OTEL_SERVICE_NAME`	`kanna-<machine name>`	OTel service.name for this install. Overrides the name derived from the computer name.
`KANNA_PROFILE_SEND_TO_STARTING`	`0`	Set to "1" to log timing for each stage between a send and the turn actually starting. Use when a chat feels slow to begin.
`KANNA_PTY_BACKGROUND_TASK_MAX_MS`	`1800000`	How long a launched background task may hold a session warm against the idle reaper (30 min). Only applies to a session with no live task list from the SDK; when the SDK reports its background tasks, set membership decides and this deadline is never consulted. The KANNA_PTY_ prefix is historical.
`KANNA_PTY_SANDBOX`	`(unset)`	Set to "off" to disable the PTY driver's OS-level sandbox. On by default on macOS, and on Linux when bubblewrap (bwrap) is on PATH. Turning it off loses defense-in-depth against the CLI's built-in credential reads; it also silences the warning logged when bwrap is missing.
`KANNA_RELOADER`	`supervisor`	Self-update reload strategy: "supervisor" (default, end-user) or "pm2" (self-host, requires KANNA_REPO_DIR).
`KANNA_REPO_DIR`	`(unset)`	Repo checkout the pm2 reloader pulls/rebuilds. Required when KANNA_RELOADER=pm2.
`KANNA_SERVER_SECRET`	`(random per process)`	Stabilises HMAC tool-request ids across process restarts.
`KANNA_STACK_MEMORY`	`enabled`	Set to "disabled" to stop a multi-root (stack) spawn from loading each additional project's CLAUDE.md / .claude/rules. Enabled, Kanna sets CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD on any spawn that has additional roots, so a chat that can WRITE a bound project also reads its conventions — at the cost of those memory files in every turn's context. A single-project chat is unaffected either way.
`KANNA_SUBAGENT_IDLE_TIMEOUT_MS`	`300000`	Idle window after which a keep-alive subagent session is auto-closed. Reset on each turn.
`KANNA_SUBAGENT_MAX_LIVE`	`5`	Max concurrent keep-alive (warm) subagent processes per chat. Over cap, delegate_subagent({keep_alive:true}) fails CAP_EXCEEDED.
`KANNA_SUBAGENT_RUN_TIMEOUT_MS`	`(orchestrator default)`	Stall watchdog for a single subagent run. The Settings value wins over this; this wins over the built-in default. Read once at server start.
`KANNA_UPDATE_COMMAND`	`(auto-detected)`	Overrides the command Kanna runs to install a self-update. Set it when npm, bun, pnpm and yarn are all absent or the wrong one is picked.

To regenerate this table after adding a new env var:

cd wiki && bun run scripts/extract-env-vars.ts

Hand-curated descriptions live in wiki/scripts/extract-env-vars.ts under DESCRIPTIONS. Vars with no description are flagged in the table.

Only vars the scan actually finds in src/ are published, so a description written for a var the code does not read is dropped rather than documented into existence. Test-only knobs are skipped.