Security

What Klatch protects, in plain words. The full version with the code and test behind every claim is threat-model.md.

The idea

An agent reads text it cannot trust: files in your repo, issues, web pages. Anything it reads can try to talk it into doing harm. So Klatch assumes an agent can be fully hostile, and limits what it can do instead of hoping it behaves.

1. No credentials that matter. An agent holds nothing that can push code, deploy, send an email or spend money. Only the hub does, and only for the exact thing you approved.
2. No way out. Agents run on a Docker network with no route to the internet. The hub's proxy is the only exit and it only lets through an allow-list (the AI provider, package registries). Every refused address is logged.
3. Approve means this exact thing. A push card shows the real diff. The hub pushes that commit, to a branch the project allows, never forced. If the agent changes anything afterwards, the card no longer matches and nothing is pushed.
4. A locked panel. One owner, an scrypt password hash, an optional authenticator code, 5 tries a minute per address, a cap on failures overall, same-origin and Host checks on every request. Agents cannot reach the panel at all.
5. Containers with little power. No Linux capabilities, no new privileges, memory, CPU and process limits, a non-root user.

Your secrets

• API keys and tokens you enter in the panel are encrypted (AES-256-GCM) with a key in .env. A copy of the database alone reveals nothing. They are never sent back to the panel, only "set" or "not set".
• Git tokens are passed to git through the process environment and never written to disk or into a repo.
• The AI key an agent needs for its turn is handed to that one container. That is the single secret an agent sees. Use a key with a spending limit.
• Your license key is stored the same way. Klatch sends it to Dodo Payments (to check it) and to nobody else.

What Klatch sends out

Klatch contacts Dodo Payments to activate and check your license (at start and about once a day). It sends your key and a name for this server, nothing about your code or your usage. If the license server cannot be reached, you get 14 days of grace. There is no other call home, no analytics and no crash reports.

Risks you accept

• The hub owns the Docker socket, which is root on that server. If someone takes over the hub, they own the server. Give Klatch a machine you are happy to trust it on, and keep the hub's address private or behind HTTPS.
• Allowed hosts are a way out. An agent can still talk to the AI provider and package registries. A hostile agent could misuse those. The audit log shows refused hosts; allowed ones are the weak spot.
• You can click Approve without reading. The cards are there to make reading easy. Nothing is ever auto-approved.
• Prompt injection cannot be prevented, only contained. That is why agents hold no secrets and no exit.
• tailnet mode has no login. Use it only on a private network. Use password for anything else.
• The server's firewall is yours. Traffic from the agents' network to the server's own services should be blocked (iptables -I INPUT -i br-<id> -j DROP). scripts/escape-suite.sh shows what an agent can reach. Klatch does not change your firewall.
• Backups hold your secrets. Keep them private.

Keeping it safe

• Use HTTPS (the installer does this with --domain) and a long password, ideally with the authenticator code.
• Give git tokens the smallest scope that works, for the repos you use.
• Keep Klatch up to date: klatch update.
• Back up, and copy backups off the server.

Reporting a problem

Please report privately: see SECURITY.md.