Security

Kanna runs agents on your machine with your credentials. This page is about what that means and which controls are real.

Durable approval protocol

Plan-mode approvals and AskUserQuestion prompts are parked as durable requests rather than in-memory promises. A pending request survives a server restart (resolved fail-closed as session_closed on boot) and replays to the browser on reconnect, so a question cannot silently strand a chat.

Set KANNA_MCP_TOOL_CALLBACKS=1 to route them, plus a set of built-in tool shims, through that protocol. Optional KANNA_SERVER_SECRET stabilises request ids across a process lifetime.

Requests time out after 600 s as an explicit deny — never as an approval.

Password gate

kanna --password <secret> puts a password gate in front of the WebSocket and every /api route. A browser signs in once and receives a kanna_session cookie (HttpOnly, SameSite=Strict, Secure over https); the password itself is never stored in the browser. Sessions last auth.sessionMaxAgeDays (default 30) and survive server restarts.

Sessions and the password hash are managed by Better Auth in auth.db under the data directory, signed with a generated auth-secret beside it; both files are readable only by your user. Repeated wrong passwords are throttled: after three sign-in attempts in ten seconds the login answers 429 until the window passes. Starting Kanna with a different --password signs every browser out.

The remote MCP server is served outside the cookie gate because its clients cannot hold a browser cookie: /mcp and the OAuth endpoints authenticate with a bearer token or the launch password instead, share the same rate limiter, and answer 404 when no --password is set.

Use it for any instance reachable beyond localhost. Kanna does not terminate TLS — put it behind a reverse proxy or a Cloudflare tunnel (Self-host basics).

Share links are public by token

A read-only share link is unauthenticated by design: /share/:token is one of the only two paths that bypass the password gate, and the 256-bit token in the URL is the entire credential. Treat a share URL as a secret, and revoke it when you are done.

Beacons reach other machines

A beacon lets the agent read, and optionally run commands, on another machine you paired. Pairing is refused, and Kanna rejects every beacon connection, until a password is set. Each machine’s scope is default-deny, every call outside what you pre-approved raises an approval prompt, and the beacon re-checks its own folders and command switch before it acts. Revoke a machine under Settings → Beacons and the agent loses access at once.

Isolation between agents

Kanna does not sandbox the agent process — it runs with your user’s permissions and can read and write whatever you can. What it does give you is separation between concurrent agents: starting work on a board card puts that agent in its own git worktree on its own branch, so three agents working at once cannot touch each other’s files.

If you need stronger isolation than your own user account:

• Run Kanna inside a dedicated VM or container with no host credential access.
• Keep plan mode and AskUserQuestion routed through the durable approval protocol above, so gates stay in your hands.
• Give the agent a checkout it is allowed to break, not your only copy.

Credential storage

Claude OAuth tokens, custom MCP server credentials and OAuth state all live in ~/.kanna/data/settings.json, written with your default file mode, not 0600 (on a shared machine, chmod 700 ~/.kanna/data). Kanna stores nothing outside ~/.kanna, and sends credentials nowhere except the provider they belong to.

Back that file up as a secret, or exclude it from backups entirely.

What Kanna does NOT do

• No code upload. The agent runs locally as a claude / codex subprocess. Only the prompts and tool output you send reach a model.
• No remote control surface beyond a Cloudflare tunnel you approve per expose_port call, --share / --cloudflared that you pass yourself, or a beacon you install and pair on a machine of your own.
• No credential storage outside ~/.kanna.

Telemetry is the one thing that leaves the machine by default: OpenTelemetry traces and metrics (turn timings, subagent runs, process memory — never prompt or code content) go to Kanna’s collector. It is a single switch under Settings → General → Telemetry Tracing, and turning it off stops the export immediately.