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.

Port, password and data directory are not env vars

KANNA_PORT, KANNA_PASSWORD and KANNA_HOME do not exist. Kanna has never read them, and setting one does nothing.

• Port and password are CLI flags: kanna --port 8080 --password <secret>. See Self-host basics.
• The data directory is always ~/.kanna — it follows HOME, so relocating it means running Kanna with a different HOME.

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_BEACON_AUTO_UPDATE	enabled	Read by a beacon, not by the Kanna server. Set to "disabled" to stop the beacon from updating itself when it connects to a newer Kanna; Update now in Settings → Beacons still works. An app opened from Finder, the Start menu or at sign-in does not see shell variables.
KANNA_BEACON_HOME	~/.kanna-beacon	Read by a beacon, not by the Kanna server. The folder where the beacon keeps its key, its state and the app record; the app and the CLI on one machine share it.
KANNA_BEACON_RELEASE_BASE	https://github.com/cuongtranba/kanna/releases/download	Read by the command-line and Windows 7 beacons, not by the Kanna server or the desktop app. Replaces the location a beacon downloads its update from, for testing against a local copy of a release. Kanna cannot set it.
KANNA_CLAUDE_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.
KANNA_CLAUDE_DRIVER	(unset)	Ignored. The PTY driver was removed and every Claude chat runs on the Claude Agent SDK. Setting it to "pty" only logs a warning at boot; leave it unset.
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_GENUI	enabled	Set to "disabled" to stop teaching the agent the ```kanna-ui generative-UI format and to turn off the end-of-turn check that asks it to fix a view that would not render. Views already in a transcript keep rendering, and the validate_ui tool stays registered.
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_NATS_RELEASE_BASE	https://github.com/nats-io/nats-server/releases/download	Where the embedded service bus downloads nats-server from. Machine-local test override; every download is still checked against that base's SHA256SUMS.
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_PROACTIVE_COMPACT	disabled	Set to "enabled" to restore Kanna's own proactive /compact injection. Off by default because the Claude Code CLI auto-compacts on its own (Settings.autoCompactEnabled, on by default), and Kanna's threshold is lower, so both running means Kanna always wins and the CLI never compacts. Turn it on only if you have set autoCompactEnabled: false in your CLI settings.
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	(unset)	Former name of KANNA_CLAUDE_BACKGROUND_TASK_MAX_MS. Still read, but only when the new name is unset.
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_RUNTIME_PROFILE	prod	Set to "dev" to use a separate data root (~/.kanna-dev instead of ~/.kanna), so a development run cannot touch real chats. `bun run dev` sets this for you.
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.
KANNA_WEBHOOKS	enabled	Set to "disabled" to turn off inbound webhooks. Every /hooks/<id> request then answers 404, as if the hook did not exist. Hooks you created are kept and work again when you remove the variable.

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.