Features Security Sandboxing

Durable approvals, the password gate, share-link exposure, and what Kanna does not do.

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).

Cross-site request guard

Every request passes one origin guard before any route runs, with or without a password. It stops a web page you happen to visit from driving Kanna through your browser:

• /ws and /beacon. A browser always sends an Origin header on a WebSocket upgrade. If it is present and is not this server's own origin, the upgrade answers 403. Beacons and scripts send no Origin and are not affected.
• /api writes (POST, PUT, PATCH, DELETE). A browser that reports Sec-Fetch-Site must report same-origin (or none); otherwise a present Origin must match. A request with a session cookie but neither header is refused. Reads such as downloads and share links are never blocked.
• Left to their own credentials. Webhooks (/hooks/:id), the remote MCP server and its OAuth endpoints, beacon transfers and /auth/* skip the guard; each carries a secret or token, or checks the origin itself.

Without --password, Kanna on the default 127.0.0.1 bind also checks the Host header and answers 403 unless it is 127.0.0.1, localhost or [::1]. That defeats DNS rebinding, where a hostile site re-points its own name at your loopback address. Open the app through one of those names; a LAN IP or machine name needs --remote or --host.

--remote, --host and --share without --password are unprotected: the Host check is off, and anyone who can reach the port can start agent turns that run commands on your machine. Kanna still starts, and logs a warning. Set --password for any instance reachable beyond your own machine.

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.