Security and data

Security and data

Who can reach Kelpy

Kelpy listens on 127.0.0.1 only: from another computer it is reached through an SSH tunnel, never directly. It rejects requests whose Host is not its own loopback address, which protects against DNS rebinding, and state-changing requests from other web pages. The Web UI cannot be embedded in other pages.

The API answers only authenticated requests:

• Browsers sign in with the access code printed in the terminal. The one-click link carries the code after #, which browsers never send to the server, and the Web UI removes it from the address bar. The code is exchanged for a session valid until Kelpy stops or you sign out. The Web UI keeps the session in the browser's storage for its own address and port, never in a cookie, which browsers would also send to other programs on the same computer.
• The command line (kelpy status, kelpy stop, kelpy provider) uses a token in data/runtime.json, a file only the user who started Kelpy can open.

The code and the token are random and new at every start. The code has 8 characters; after 5 wrong codes, one more attempt is allowed every 10 seconds, even with the right code.

A page that was signed in never asks for the code by itself: when its session ends, it says so and asks you to open the link shown in the terminal. Another program could take Kelpy's port while Kelpy is stopped, and a code typed into its page would let it into Kelpy.

For the same reason, a page that holds a session checks who answers before sending it: Kelpy proves that it knows the session by signing a random challenge with it, and the session itself never travels for the check. The page does this when it opens, every few seconds while it is open, and before any request when the last check is more than a second old. If the answer does not come from the Kelpy that issued the session, for example because an SSH tunnel dropped and another program took its local port, the page shows Disconnected and sends nothing, and it resumes by itself when Kelpy answers again.

What the check cannot cover: a page loaded from the port while another program holds it runs that program's code, which can read what the browser keeps for that address, the session included. Open Kelpy only from the link it prints, and if a tunnel dropped, make sure it is up again before you reload the page.

What Kelpy stores

Everything is in the Kelpy home:

Where	What
config.toml	the AI provider, model and address; never an API key
data/kelpy.db	conversations, the summaries of their older messages, and the Command log (SQLite)
data/runtime.json	the running Kelpy's PID, address, access code and command-line token; removed when it stops
data/chatgpt.toml	the ChatGPT agent registration: this installation's id, the app's id and its account; no secrets
data/chatgpt-session.toml	only with Save the sign-in on this computer: what renews the ChatGPT session, never an access token
data/last-port	the port of the last start
memory/	what Kelpy knows about this server, as Markdown
workspace/	the default folder for the agent's work

data/ is readable only by the user who started Kelpy. API keys entered in the Web UI or the terminal are kept in memory only, until Kelpy stops.

What leaves the computer

Kelpy connects only to the AI service you chose, and for a ChatGPT plan to OpenAI's sign-in service. Your messages, the conversation so far and memory/MEMORY.md are sent to that service with every message; in a long conversation, a summary of the older messages, written by the same service, takes their place. With System access Read-only, what Kelpy reads on the system goes too: command output as it is, as Kelpy does not yet remove secrets from it, and the files it reads, never those that may hold secrets (see System access). With a local model all of it stays on your network, except with Ollama's cloud models.

When Kelpy stops

New work is refused at once, answers being written are stopped and saved as interrupted, and open connections get at most 10 seconds to close. Browser sessions and API keys end. A ChatGPT session is revoked at OpenAI, unless you saved the sign-in on this computer. Nothing of Kelpy keeps running.