Reference
Configuration
kandown.json, environment variables, the update check, and the daemon's security model.
.kandown/kandown.json
Per-project configuration: columns, theme, notifications, workflow selection and kandown work
compiler settings. It is a plain JSON file, committed with your repository, so a colleague who clones
the project gets your board setup with it.
Edit it through Settings in the web board, kandown settings in the terminal, or by hand.
Columns
Column names are free-form. Each column has a semantic role (backlog, ready, active,
review, terminal, or custom) plus optional agent guidance. The dependency gate protects the
column with the terminal role. Legacy configs without roles retain last-column compatibility.
If several columns share a role, board order wins and the first matching column is authoritative.
Themes
38 built-in themes plus custom themes defined as JSON, along with radius, shadow, density, motion and font-stack tokens. See Appearance.
Workflow and agent output
workflow.active selects one exclusive package. workflow.skills adds compatible Markdown
skills, while workflow.trackingCadence controls update frequency independently from
agent.workOutput.detailMode. The immutable core cannot be removed or reordered. See
For AI agents.
.kandown/kandown_work.md
Your project's agent instructions, injected into kandown work. See
Project instructions.
Environment variables
| Variable | Effect |
|---|---|
KANDOWN_NO_UPDATE=1 | Disable the background update check (recommended in CI) |
KANDOWN_DEBUG=1 | Print full stack traces instead of a one-line summary |
KANDOWN_AGENT_HOOK_URL | Endpoint that receives tasks from Send to Agent / TUI g |
KANDOWN_AGENT_HOOK_LABEL | Custom label for the agent hook button |
KANDOWN_AGENT_HOOK_HEADERS | JSON object of extra headers for the hook request |
The update check
Interactive runs check npm for a newer version at most once every 24 hours and install it silently when one is found. It is skipped:
- for every task command,
- for
kandown daemon, - whenever stdout is not a terminal.
In other words it cannot fire in CI or inside an agent loop. KANDOWN_NO_UPDATE=1 removes it
entirely.
Security
The local daemon binds to 127.0.0.1 only and mints a random per-project API token at
startup. The token is stored in the gitignored .kandown/daemon.json and injected into the page it
serves.
Every route except the read-only GET /api/daemon identity check requires that token, so an
unrelated browser tab cannot reach your tasks by scanning localhost ports (a real attack against
naive local servers. Task ids are validated before they touch the filesystem, which closes the path
traversal that "id" parameters invite.
Careful
.kandown/daemon.json holds a live credential and is gitignored for that reason. If you have
custom ignore rules, make sure it stays out of your commits.
What leaves your machine
Nothing, with exactly two exceptions, both of which you control:
- The update check, which contacts the npm registry (disabled with
KANDOWN_NO_UPDATE=1). - The agent hook, which posts a task to your own endpoint (only when you press the key, and only to the URL you set.
No telemetry, no analytics, no account, no sync.