Configuration
Configuration lives in .env next to docker-compose.yml, with two exceptions: SMTP is set in the PocketBase admin UI, and AI can also be set right in the app (Organization settings → AI features). The complete variable list with defaults is in Environment variables; this page covers the decisions rather than the table.
After any change to .env:
docker compose up -d --buildAI
AI is off by default and the app is fully usable that way. Switch it on with the KB_AI_PROVIDER switch — in .env, or in the app under Organization settings → AI features (five cards; the configuration from the server's .env file currently applies — saving overrides it).
| Provider (card) | What it means |
|---|---|
none — Disabled | No AI. Nothing ever leaves your server. This is the default. |
openai — OpenAI-compatible | Any OpenAI-compatible API. OpenAI, OpenRouter, Groq, Mistral, Together — or your own vLLM, LM Studio, llama.cpp or liteLLM proxy. Address, key, model name. |
ollama — Your own Ollama | Your own local model. Install Ollama, ollama pull gpt-oss:20b, then KB_AI_URL=http://IP:11434 and KB_AI_MODEL=gpt-oss:20b. Everything stays inside your network. |
api — AI service via API | A remote AI service compatible with the killBottleneck API — an address and token from your provider. No GPU of your own and no maintenance. |
custom — Custom endpoint | Your own layer honouring the same contract — the contract is written down here. The assistant on the side and image reading do not run with it. |
Where your data goes
With any provider other than none, map data is sent to the endpoint you configured. With ollama pointing at a machine you own, that is still your network. With openai, api or custom it is whatever you pointed it at. There is no third option hidden anywhere. The key is stored on your server and is never handed back to the browser; requests are billed by your provider, not by us.
OpenAI-compatible (openai)
Almost every provider today speaks the OpenAI shape, so one switch covers them all. You need three things: the base address (it usually ends in /v1), your API key, and the exact model name your provider uses.
KB_AI_PROVIDER=openai
KB_AI_URL=https://openrouter.ai/api/v1
KB_AI_TOKEN=sk-...
KB_AI_MODEL=openai/gpt-4o-mini| Service | KB_AI_URL | Example KB_AI_MODEL |
|---|---|---|
| OpenAI | https://api.openai.com/v1 | gpt-4o-mini |
| OpenRouter | https://openrouter.ai/api/v1 | openai/gpt-4o-mini |
| Groq | https://api.groq.com/openai/v1 | (name from your provider) |
| vLLM / LM Studio / llama.cpp | http://IP:PORT/v1 | (the name the server reports) |
Write the address down to the version
The address must point at the root of the OpenAI interface. If your service sits on a sub-path (a liteLLM proxy behind https://company.com/llm, say), write it out in full, including the version — https://company.com/llm/v1. From a bare address we cannot tell whether the service lives at the root and wants /v1 appended (that is how OpenAI does it) or sits exactly there, so we append /v1 whenever the path carries no version. An address that already contains a version anywhere in its path (…/v1beta/openai) is left alone. Got it wrong? Test connection tells you at once.
Which model to pick for openai — measured, not guessed
Measured on 20 Aug 2026 by running six AI features of killBottleneck (map from a goal, clarifying questions, sub-steps, map from text, chat over a map, morning summary) through the product itself, in Czech. Price is what those six calls actually cost. (The "Suggest with AI" and "Map from text" dialogs have since been replaced by the assistant on the side — the models do the same work, just from the panel.)
| Model | Passed | Map from a goal | Six features cost |
|---|---|---|---|
gpt-4o-mini ⭐ | 6/6 | 11.2 s, 8 nodes | $0.0011 |
gpt-4.1-mini | 6/6 | 6.4 s, 7 nodes | $0.0025 |
gpt-4.1-nano | 6/6 | 2.8 s, 7 nodes | $0.0005 |
gpt-5-mini | 6/6 | 24.5 s, 7 nodes | $0.0120 |
o4-mini | 6/6 | 16.8 s, 7 nodes | $0.0329 |
gpt-5-nano | 3/6 ❌ | 26.2 s, 7 nodes | $0.0044 |
gpt-4o-mini is the recommended default. gpt-4.1-nano is cheaper and quicker and passed everything too; gpt-4.1-mini sits in between.
⚠️ Avoid reasoning models (gpt-5-*, o4-*). They are 2–4× slower and 5–30× more expensive, because you also pay for the thinking you never see — o4-mini spent 5,824 of its 7,082 output tokens on reasoning. And gpt-5-nano loses three of the six features outright: it burns the whole budget on thinking and returns nothing. If you want a reasoning model anyway, KB_AI_REASONING_BUDGET and KB_AI_REASONING_EFFORT give it room (see the reference).
The exception measured later (7 Nov 2026) is gpt-5.6-luna for the assistant: about 8 s per task over 20 everyday tasks, because with tool calling it runs with reasoning off (since v1.0.1 automatically). Details in Your own OpenAI key.
The quickest check for any other model is Test connection followed by letting the home page suggest a project with AI (the assistant asks a few questions and builds the tree): either a map appears, or you get an error saying what went wrong.
Your own Ollama (ollama)
KB_AI_PROVIDER=ollama
KB_AI_URL=http://192.168.1.10:11434
KB_AI_MODEL=gpt-oss:20bkillBottleneck talks to Ollama directly (/api/chat) — nothing sits in between and nothing leaves your network. A local model costs nothing; the hourly spending cap does not apply to it.
Which model to pick for Ollama
gpt-oss:20b is the verified one — killBottleneck is tested against it and its answers make sense in Czech as well. Plan for what it needs:
| Model size | ~14 GB |
| Sensible operation | a GPU with 16 GB of memory or more |
| Answer time | seconds to tens of seconds (~23 s measured for suggesting questions) |
You are free to try another — Ollama offers plenty — at your own risk. It is not about how "smart" the model is: killBottleneck needs a machine-readable answer (JSON) and tool calling for the assistant; smaller or reasoning models sometimes return it truncated — the feature then silently does nothing. Of the ones we measured, gemma3:12b (~8 GB) held up and is usable on a 12 GB card, just slower. For the assistant, gemma4, qwen3 and gpt-oss have worked well.
Without a GPU the model runs on the CPU and answers take minutes; that is not enough to work with.
Speech-to-text (voice notes)
Voice notes in the assistant need a speech-to-text service. The microphone shows up in the app only when there is one — a microphone that always fails is worse than no microphone.
| You have | What to set |
|---|---|
openai at OpenAI | Nothing — the same service transcribes (/audio/transcriptions, default model whisper-1; gpt-4o-mini-transcribe is cheaper and, on our sample, just as accurate — change it with KB_AI_TRANSCRIBE_MODEL or in the Transcription model field). |
openai at Groq | The model is named differently: KB_AI_TRANSCRIBE_MODEL=whisper-large-v3. |
openai at OpenRouter, vLLM, LM Studio | They usually have no transcription. Set a separate transcriber with KB_TRANSCRIBE_* (speaches, whisper.cpp server, faster-whisper-server) — or the microphone stays hidden. |
ollama | The same: Ollama does not transcribe speech, add KB_TRANSCRIBE_*. |
api | Transcription is provided by the service provider. |
The recording goes only to the transcription service and is not stored; the microphone works only over HTTPS (or on localhost). Details on KB_TRANSCRIBE_VAD and the other options are in the reference.
A cap on spending
With your own API key every AI call costs you money, so one person can run at most 60 AI operations per hour by default (KB_AI_MAX_PER_HOUR); in the assistant a voice note counts as 2 of them, a photo as 3 and an attached PDF as 2. Without a cap a single account — or a stuck browser tab — could burn your credit in a loop. Above the cap the app says You have used up the hourly cap of AI operations (60) and nothing is lost. For the assistant the cap applies with every provider; for the wand, the project summary and the other small helpers only with openai — a local Ollama costs nothing and the AI service via API has its own quota. (KB_AI_MAX_TRANSCRIBE_PER_HOUR, 20 by default, caps direct calls of the transcription API.)
The second cap is weekly and per organization: the AI credits section in Organization settings shows usage in turns (1 turn ≈ one ordinary message to the assistant) per person and week, and can set Turns per week with a reserve for administrators. The operator can cap it from above with KB_AI_KVOTA_TYDEN. The section appears as soon as the assistant is configured.
The assistant on the side
The assistant — the panel on the right you dictate to, send whiteboard photos and PDFs, and ask to prepare meetings — is the main road to AI today. What it needs:
- A model at
ollamaoropenaithat supports tool calling:gpt-4o-mini,gemma4,qwen3,gpt-oss. The assistant's own model (KB_CHAT_*) is used when set, otherwise the general AI settings. When neither points atollamaoropenai(the general AI isapi,customornoneandKB_CHAT_PROVIDERis empty), the Assistant button in the header does not appear. - A dedicated model just for the assistant (optional):
KB_CHAT_PROVIDER/_URL/_MODEL/_TOKENoverride the general settings — say a cheap model for the wand and a stronger one for the assistant. With Ollama setKB_CHAT_NUM_CTX(otherwise Ollama cuts the longer prompt at 4096 tokens). - Images (photos of notes, screenshots): tick Assistant reads images in AI features (after saving, the model is tried on a built-in image and images are switched on only if it really reads it), or
KB_VISION_*in.env— it can be a different model from the text one. - Voice notes: speech-to-text as in the table above.
- Two models at once (
KB_CHAT_HYBRID): a light one for reading and briefings, the main one for writes — for those who save tokens. Details in the reference.
AI manager and Structure manager
Two extra roles, independent of the administrator, are switched on in Organization settings next to a person: the AI manager receives the "I would like this automated" requests and keeps the AI agent registry; the Structure manager draws the org structure and names deputies. Until you appoint someone, the administrator does both.
A separate model just for daily summaries
The one-line encouragement in My day is short formatted text — a smaller, faster model is plenty. KB_SUMMARY_PROVIDER / _URL / _MODEL / _TOKEN override the general AI config for that one job. Left empty, the general configuration is used.
The summary is generated in the morning at KB_SUMMARY_HOUR (default 6) only for accounts that signed in within KB_SUMMARY_ACTIVE_DAYS days (default 14, 0 = everyone); everyone else gets theirs when they open the app. The AI never enumerates your task lists — those are computed from your data and clickable. Turning AI off costs you exactly one line in My day.
Registration and the registration key
The first account to register becomes the administrator. After that, either people register themselves, or an administrator or manager invites them from Organization settings (Invite user).
Set KB_SETUP_CODE and every registration requires that key (the Organization registration key field). Hand it to the people you want to let in. An invitation from an administrator does not need the key.
Reachable from the internet?
Set KB_SETUP_CODE before you expose the instance. Empty means open registration.
Sign in with Google
Optional — users then sign in with Google instead of e-mail and password.
- In the Google Cloud Console: APIs & Services → Credentials → Create credentials → OAuth client ID → Web application.
- Under Authorized redirect URIs add:
https://YOUR-DOMAIN/api/oauth2-redirect - Put the values in
.env:bashKB_GOOGLE_CLIENT_ID=…apps.googleusercontent.com KB_GOOGLE_CLIENT_SECRET=… docker compose up -d --build— the Sign in with Google button appears by itself.
Empty variables = Google sign-in is off and the button is not shown. The same OAuth client plus KB_GOOGLE_PICKER_API_KEY enables picking attachments straight from Google Drive (they are stored as links).
E-mail (SMTP)
SMTP is configured in the PocketBase admin UI, not in .env:
http://SERVER-IP:8090/_/ → Settings → Mail settings
Create the superuser account with the link from docker compose logs (see Installation).
What changes if you skip SMTP
E-mail is off by default and the instance is fully usable that way. Only these differ:
| With SMTP | Without SMTP | |
|---|---|---|
| Inviting a member | e-mailed with a link | the admin is shown a temporary password to hand over |
| "Forgot your password?" | self-service, link arrives by e-mail | not offered — the admin resets it (see below) |
| Sharing a map with an address without an account | a registration invitation goes out (daily caps KB_SHARE_INVITE_*) | the dialog offers Copy registration link |
| Reminders and daily digest | delivered per each person's preferences | in-app bell only |
Bug reports and ideas (KB_REPORT_TO) | a menu item, reports go to your address | the item is not shown at all |
The password-reset link is hidden on purpose without SMTP: the server would confirm the request, no message would arrive, and the person would wait for mail that does not exist. Notification e-mails are off by default even with SMTP and follow each user's preferences; KB_NOTIFY_EMAIL_DEFAULT=1 keeps the old "on until the person turns it off" behaviour.
Forgotten password without SMTP
For a team member, the admin resets it: Organization settings → key icon next to the person → confirm Reset the password for …?. A new temporary password appears to hand over (Password changed. Hand the new one over in person — it will not be shown again.); the old password stops working immediately and the person is signed out everywhere. They are told in the bell that someone reset it.
For the admin, nobody can do this — there is no one above them. On your own server without SMTP the route goes through the PocketBase admin UI, which you have access to as the operator:
http://SERVER-IP:8090/_/→ sign in as superuser- users collection → find your account → Change password
No superuser yet? Create one on the server (service name comes from docker-compose.yml):
docker compose exec killbottleneck /app/pocketbase superuser upsert you@example.com 'YourStrongPassword'Hosted version (killbottleneck.com)
E-mail always works there, so the admin uses the normal "Forgot your password?" on the sign-in page. Nothing else to handle.
Watch out
The console on :8090/_/ runs over plain HTTP — open it only from your local network or through an SSH tunnel, never over the internet. A password typed on the command line also stays in your shell history; change it in the console afterwards and delete the history entry. Recommendation: create a second account with the administrator role and keep its password in a password manager.
Instance appearance
The default look for everyone (skin, logo, organization name) is not set in .env but in the app: Organization settings → Default instance appearance and Organization. See Skins and Organization settings.
Time zone and recurring templates
TZ applies to the whole instance, not per user. It decides which zone "every Monday", "at 5 in the morning" and a "14:00" reminder are counted in. A team spread across zones gets the server's zone.
If the server was powered off during KB_AUTO_HOUR, recurring projects are created at the next later hour the same day — they are not silently skipped.
Attachment limits
KB_FILES_MB caps uploaded files across the whole instance:
- empty — no limit; the self-hosting default, it is your disk
- a number — cap in MB (
5000= 5 GB) 0— uploading disabled; attachments can still be added as links, which take no space and always point at the current version of the file
Why 0 is the default on our hosted version
It is not about saving disk space, it is deliberate: we do not store other people's files. They never enter our backups, they do not turn into "we process customer documents" in a contract, and they stay where they already are. On your own server it is your disk and your call.
Automations
Only relevant if you drive goals from an automation. KB_PUBLIC_URL is the address the agent should call back on — see Environment variables → Automations for why leaving it empty can make a remote agent call itself, and why KB_ALLOW_PRIVATE_WEBHOOKS is off by default.
Instance mode
Leave KB_HOSTED empty on your own server. It exists for instances that run at a provider alongside other customers, where the instance administrator must not be able to point the AI service into a private network and probe the neighbours; it also switches off the check for new versions (the operator updates there).
Related
- Environment variables — the complete table
- AI assistant — what you get once AI is configured
- Organization settings — the AI features, AI credits, people and roles sections
- HTTPS and a reverse proxy — the microphone and agent OAuth need HTTPS

