Repository navigation
Connecting to AI
Kelpy needs a model to talk to. Choose it in the Web UI, which asks on first use (later: the provider menu in the
top bar, Change provider), or run kelpy provider in a terminal. There are four ways:
| Way | Paid by | Where prompts go |
|---|---|---|
| ChatGPT plan | the ChatGPT plan you already have | OpenAI |
| Free online service | nobody, within the service's limits | the service; some may use them for training |
| API key | per use, to the provider | the provider |
| Local model | your hardware | your network, except Ollama's cloud models |
The choice is saved in config.toml. API keys are never written to disk: a key entered in the Web UI or in the
terminal stays in memory until Kelpy stops, and the Web UI asks for it again at the next start.
After the service, choose the model. Kelpy asks the service for its list: the recommended models come first, then the others; you can also type a model's name.
Answers are paid by your ChatGPT plan, as Codex usage within its limits. There are two ways to sign in:
| Sign in as Codex CLI | Sign in as an agent | |
|---|---|---|
| How | Kelpy shows a short code, with its address and a QR code; you approve it on any device | Your browser opens OpenAI's page, then comes back to Kelpy |
| Registration | none | the first sign-in of each installation registers an app in your ChatGPT account and asks its name |
| Usage | counts as Codex usage, with no limit of its own | shown apart, with a weekly limit if you set one, revocable on its own |
| Limits | uses the Codex CLI's sign-in, not OpenAI's program for apps, and may stop working | after approval the browser must reach Kelpy: through an SSH tunnel, or by pasting the address it shows |
| Suits | starters, servers without a browser, many servers | usage that must be limited or tracked apart |
Signing in as Codex CLI requires sign-in with a code to be enabled in ChatGPT's security settings.
The session ends when Kelpy stops, and Kelpy revokes it. With Save the sign-in on this computer, it survives
restarts instead: Kelpy saves what renews it in data/chatgpt-session.toml, never an access token, until you sign
out. Sign out revokes the session at OpenAI and deletes that file.
As an agent, Kelpy is registered in one ChatGPT account. Forget registration lets the next sign-in register
again, with any account; it is refused while a session uses the registration. The app stays in your ChatGPT
account until you remove it there. To reuse a registration on another server without registering again, use
Download registration file on one Kelpy and Upload registration file… on the other, or run
kelpy provider --export-agent <FILE> and kelpy provider --import-agent <FILE>. The file holds no secrets.
Each needs an account and an API key; the Web UI shows the steps and links to the page where the key is created. Free tiers change often; these terms were checked in October 2026.
| Service | Free tier | Data |
|---|---|---|
| Google Gemini | daily limits shown in AI Studio | outside the EEA, Switzerland and the UK, Google may use prompts and answers to improve its products, and people may read them |
| Groq | about 30 requests per minute and 1,000 per day for each model | not kept by default |
| OpenRouter | models ending in :free, within 20 requests per minute and 50 per day (1,000 per day once 10 credits have been bought) |
providers that may train on prompts are used only if allowed under Settings, Privacy |
| Mistral | the Experiment plan, with low rate limits; needs a verified phone number | requests may be used to train Mistral's models |
If OpenRouter refuses a free model, check Settings, Privacy: some free models need providers that may train on prompts.
| Service | Key |
|---|---|
| Anthropic (Claude) | from the Claude Console; Claude Max, Ultra and Team plans include monthly API credits that pay for it. ANTHROPIC_API_KEY is used if set |
| OpenAI | from the OpenAI Platform, billed per use and separate from ChatGPT plans. OPENAI_API_KEY is used if set |
| Other service | any service with an OpenAI-compatible API: enter its address, model and key |
In the terminal, kelpy provider --service <ID> --model <NAME> --key-from <VARIABLE> reads the key from an
environment variable: see Command line.
Ollama, on this computer or another one on your network. Leave the address empty for Ollama on this computer
(http://localhost:11434/v1), or enter http://<address>:11434/v1. The Web UI lists the installed models and
suggests others for the computer's memory, and downloads them; a download goes on if you close the dialog. Cloud
models, whose names end in cloud, run on ollama.com: their prompts leave your network.
When Ollama is not installed on this computer, Install Ollama (or kelpy provider) shows the command Kelpy would
run, Ollama's own installer on Linux and winget on Windows, and runs it once you confirm, with its output shown as it
comes; Kelpy then waits for Ollama to answer. On macOS, download it from ollama.com.
Set OLLAMA_CONTEXT_LENGTH=64000 in Ollama's environment and restart Ollama. Its default context, 4,096 tokens on
computers with less than 24 GiB of graphics memory, is too short for Kelpy: conversations have to be summarised
every few messages.
Other local server: LM Studio, llama.cpp, vLLM or another server with an OpenAI-compatible API. Enter its address and model.
Answers are streamed as they are written and keep going if you close the page; Stop interrupts them. Every open
page shows what is done in the others as it happens. Conversations are stored in data/kelpy.db. When a conversation no longer fits what the model can read, the model
summarises its older messages and Kelpy sends the summary with the recent ones. The conversation is kept whole, with
the line Earlier messages summarised for the model above the first message the model still reads in full.
Answers are concise; turn on Explanations under the message box for a conversation where you want each step explained in plain words: what it does and why, what to expect, and how to check it worked. The answer stays concise, and each explanation shows in a panel under its step; Close explanations under the answer folds them all. Every code block and panel has its own Copy, and Copy under an answer takes it whole, in Markdown.