Environment variables
Everything is configured in .env next to docker-compose.yml. Copy the template and edit:
cp .env.example .envAfter any change, rebuild — a restart is not enough:
docker compose up -d --buildOld FLOWMAP_* names still work
The variables used to be called FLOWMAP_*. Both layers — Docker Compose and the server — understand the old names, so an .env from an earlier version keeps working. Fresh installs should use KB_*.
Only what docker-compose.yml passes through reaches the container
The server also reads variables the shipped docker-compose.yml does not know (today KB_AGENT_SETUP_ASK and KB_PRIVATE_WEBHOOK_HOSTS). Those have no effect in .env — they belong in docker-compose.override.yml, which updates never overwrite:
services:
killbottleneck:
environment:
KB_AGENT_SETUP_ASK: "0"Test and hosting switches (KB_TEST_CLOCK, KB_TRIAL_UNTIL, KB_MAX_USERS, KB_CUSTOMER…) are deliberately not listed here: they serve our operations and tests, do not set them on your own server.
Basics
The only things most installations change: the port and the time zone.
| Variable | Default | What it does |
|---|---|---|
KB_PORT | 8090 | Port the instance listens on: http://SERVER-IP:PORT. |
KB_NAME | killbottleneck | Container name. Set a different one to run a second instance next to the first on the same host. |
TZ | UTC | Instance time zone. Decides which zone "day" and "hour" mean for recurring templates, daily summaries, deadline notices and timed reminders (calendar events and deadline reminders fire at HH:MM in this zone — with the default UTC a "14:00" reminder arrives at 16:00 Prague summer time). Set e.g. Europe/Prague. Applies to the whole instance — a team spread across zones gets the server's zone, not each user's. |
KB_AUTO_HOUR | 5 | Hour (0–23, in TZ) from which recurring templates create that day's projects. If the server was off during that hour, they are created at the next later hour the same day. |
KB_DEADLINE_HOUR | 7 | Hour of the morning deadline digest (0–23, local). Also the hour at which the reminder of an all-day calendar event arrives. |
AI
| Variable | Default | What it does |
|---|---|---|
KB_AI_PROVIDER | none | none = no AI at all (everything else works). openai = any OpenAI-compatible API (OpenAI, OpenRouter, Groq, vLLM, LM Studio…). ollama = your own local model. api = a remote AI service compatible with the killBottleneck API (address + token). custom = your own endpoint honouring the same contract. |
KB_AI_URL | (empty) | Endpoint address. For ollama the Ollama address, e.g. http://192.168.1.10:11434. For openai the base address, usually ending in /v1 — a trailing /chat/completions or a missing /v1 is corrected automatically. |
KB_AI_TOKEN | (empty) | Token for api / custom; the API key for openai (sent as Authorization: Bearer). |
KB_AI_MODEL | (empty) | For ollama the model to use (ollama pull <model> first); for openai the exact model name your provider expects, e.g. gpt-4o-mini. |
KB_AI_REASONING_BUDGET | 4000 | openai only, reasoning models (o-series, gpt-5* incl. GPT-5.6 Luna): output tokens added on top of the normal limit as room for reasoning — without it the model can spend the whole limit thinking and return nothing. A reasoning model is recognised by its name, by refusing max_tokens/temperature, or by reasoning_tokens in a reply (then remembered). Applies to the assistant, the AI helper, summaries and image reading. |
KB_AI_REASONING_EFFORT | low | openai only, reasoning models: reasoning_effort sent with each request (minimal/low/medium/high as the model allows; auto = do not send). A value in KB_*_OPENAI_EXTRA takes precedence; when the model refuses the value (OpenAI refuses anything but none together with tool calling), the call is repeated with none and then without the field; what worked is remembered per model. |
KB_AI_OPENAI_EXTRA | (empty) | openai only — JSON with extra request fields sent with every call, e.g. {"reasoning_effort":"none"} to switch reasoning off where the provider allows it (same as KB_CHAT_OPENAI_EXTRA, but for the general AI functions). also applies to the assistant (unless KB_CHAT_OPENAI_EXTRA is set) and to summaries. |
KB_AI_TRANSCRIBE_URL | (empty) | Speech-to-text endpoint. Derived from KB_AI_URL when empty. With openai you can leave it empty — voice notes are then transcribed by the same service; when filled in, this address wins. |
KB_AI_TRANSCRIBE_MODEL | whisper-1 | openai only — the transcription model (Groq: whisper-large-v3). Can also be set in Organization settings → AI features. |
KB_AI_MAX_PER_HOUR | 60 | openai only — AI operations one person may run per hour. Every call spends your own credit. The AI assistant on the side has its own counter with the same cap, which applies with every provider. Above the cap: You have used up the hourly cap of AI operations (60). |
KB_AI_MAX_TRANSCRIBE_PER_HOUR | 20 | Transcriptions one person may run per hour through the transcription API mode (/api/kb/advisor, mode: transcribe) — with every provider. Voice notes in the assistant count against KB_AI_MAX_PER_HOUR instead (see KB_AI_HLAS_VAHA). |
The same can be set in the app: Organization settings → AI features (provider, address, model, token, transcription, images). A value saved in the app takes precedence over .env.
Daily summary
The one-line encouragement in My day can use a separate, smaller model.
| Variable | Default | What it does |
|---|---|---|
KB_SUMMARY_HOUR | 6 | Hour of morning generation (local). |
KB_SUMMARY_MINUTE | — | Minute of that hour (0–59); empty = a fixed minute 1–30 derived from the instance address. |
KB_SUMMARY_ACTIVE_DAYS | 14 | Generate in the morning only for accounts that signed in within N days. 0 = everyone. Inactive users get theirs when they open the app. |
KB_SUMMARY_PROVIDER | (empty) | Overrides KB_AI_PROVIDER just for summaries. |
KB_SUMMARY_URL | (empty) | Overrides KB_AI_URL just for summaries. |
KB_SUMMARY_MODEL | (empty) | Overrides KB_AI_MODEL just for summaries. |
KB_SUMMARY_TOKEN | (empty) | Overrides KB_AI_TOKEN just for summaries. |
Assistant on the side
The AI assistant in the right-hand panel. The model is looked up in the order KB_CHAT_* → KB_SUMMARY_* → the general AI settings. The panel shows only with the ollama or openai provider and needs a model with tool calling, e.g. gemma4, qwen3, gpt-oss or gpt-4o-mini.
| Variable | Default | What it does |
|---|---|---|
KB_CHAT_PROVIDER | (empty) | ollama or openai — a dedicated model just for the assistant. Empty = KB_SUMMARY_* is used, then the general AI settings. |
KB_CHAT_URL | (empty) | Address of the assistant model (like KB_AI_URL). |
KB_CHAT_MODEL | (empty) | Name of the assistant model. |
KB_CHAT_TOKEN | (empty) | API key for the assistant model. |
KB_CHAT_THINK | (empty) | Model reasoning: empty = off (fastest), otherwise low, medium, high or true. |
KB_CHAT_NUM_CTX | (empty) | ollama only — context size (num_ctx) sent with every call. Ollama otherwise defaults to 4096 tokens and would silently cut the assistant's longer prompt. |
KB_CHAT_OPENAI_EXTRA | (empty) | openai only — JSON with extra request fields, e.g. {"reasoning_effort":"none"}. Reasoning models with a low token limit can otherwise spend it all on thinking and return an error the provider still bills. |
KB_CHAT_TOOLS | auto | Which tool schemas the assistant model receives. auto = GPT models (gpt-* except gpt-oss, o*, chatgpt*) get every tool on every call — they never call a tool they were not offered, so a feature without a keyword would silently disappear; other models only the groups the conversation needs (saves tokens; a tool the model asks for anyway is added and the call repeated). groups = always only the groups. all = every tool on every call. |
KB_CHAT_POTVRZENI | app | Who answers after a simple card is confirmed (adding or editing a step, sharing, appearance…): app = the app writes "Done." without calling the model, model = the model replies as before. |
KB_CHAT_MAX_TAHU | 10 | How many recent turns of the conversation the model receives (2–30). For measurements only. |
KB_CHAT_MAX_TOOL_STARE | 600 | To how many characters tool results from older turns are shortened for the model (200–12000). For measurements only. |
KB_CHAT_STALY_ZACATEK | (empty) | 1 = the list of maps at the start of the prompt is frozen for the whole conversation; maps created or renamed later are passed as a note in the conversation. Keeps the prompt start identical between calls, so models whose server caches only a prefix checkpoint (e.g. Strata) don't re-read the whole prompt. Other models don't need it. KB_CHAT2_STALY_ZACATEK = the same for the second model. |
KB_CHAT_STALE_NASTROJE | (empty) | 1 = the tool list sent to the model stays the same for the whole conversation; tool groups opened later are described in the conversation instead of being added to the list. Same purpose as KB_CHAT_STALY_ZACATEK. KB_CHAT2_STALE_NASTROJE = the same for the second model. |
KB_CHAT_HYBRID | (empty) | Two models in the assistant: a light one (KB_CHAT_LIGHT_*) for reading, briefings and drafts, the main one for writes. Comma-separated strategies: rezim = the briefing and breakdown modes go to the light model; klasifikator = the light model first decides "is this a write?" (one short call); predani = the light model starts and hands the turn to the main model as soon as it wants to write. Empty = one model. |
KB_CHAT_LIGHT_PROVIDER / _URL / _MODEL / _TOKEN / _THINK / _NUM_CTX / _OPENAI_EXTRA | (empty) | The light model for KB_CHAT_HYBRID (ollama or openai), same meaning as the KB_CHAT_* variables; _THINK defaults to low. Without a provider the hybrid stays off. |
KB_AI_KVOTA_TYDEN | (empty) | Weekly cap of AI credits (turns; 1 turn ≈ one ordinary message to the assistant) for the organization — the AI credits section in Organization settings. The value set in the app can only lower it, never raise it. Empty = no operator cap. |
Images in the assistant
An image is first transcribed by a model that can see images; the assistant then works with the text only. The original is not stored. Without KB_VISION_PROVIDER, KB_VISION_URL and KB_VISION_MODEL the assistant refuses images.
| Variable | Default | What it does |
|---|---|---|
KB_VISION_PROVIDER | (empty) | ollama or openai — the model that reads images (e.g. gemma4 / gemma3 via Ollama, or an OpenAI-compatible API with image input). |
KB_VISION_URL | (empty) | Address of the image model. |
KB_VISION_MODEL | (empty) | Name of the image model. |
KB_VISION_TOKEN | (empty) | API key for the image model. |
KB_VISION_NUM_CTX | 8192 | ollama only — context size for the image transcription. |
KB_VISION_OPENAI_EXTRA | (empty) | openai only — JSON with extra fields; for reasoning models {"reasoning_effort":"none"}. |
KB_VISION_ZALOHA_PROVIDER / _URL / _MODEL / _TOKEN / _NUM_CTX / _OPENAI_EXTRA | (empty) | Optional fallback model used when the first one fails or times out. |
KB_VISION_TIMEOUT | 45 | Seconds per transcription attempt. Keep the total well under your reverse proxy timeout (Cloudflare around 100 s). |
KB_VISION_POKUSY | 0 | Extra retries on the first model before the fallback is tried. |
KB_CHAT_MAX_IMG_MB | 1.2 | Largest accepted image in MB. The browser shrinks screenshots to about 250 kB on its own. Raising it raises the assistant's request body cap (~4.25 MB today) — behind nginx raise client_max_body_size too, see HTTPS. |
KB_CHAT_NAHLEDU | 3 | How many small image thumbnails one conversation keeps; older images keep only the transcript. |
KB_AI_IMG_VAHA | 3 | How many turns of the hourly cap (KB_AI_MAX_PER_HOUR) one image turn uses. |
KB_TRANSCRIBE_PROVIDER / _URL / _MODEL / _TOKEN | (empty) | Speech-to-text for voice notes in the assistant, in the OpenAI shape (multipart /audio/transcriptions): speaches, whisper.cpp server, faster-whisper-server, OpenAI, Groq… KB_TRANSCRIBE_PROVIDER=openai + the full URL (e.g. http://192.168.1.10:8000/v1/audio/transcriptions) and model (e.g. Systran/faster-whisper-large-v3). Empty = the general AI decides (an openai service that lists a whisper/transcribe model, KB_AI_TRANSCRIBE_URL, or the gateway). none = switch speech-to-text off. |
KB_TRANSCRIBE_VAD | (auto) | Silence filter (vad_filter=true, speaches / faster-whisper). Default on for your own KB_TRANSCRIBE_URL unless it points to OpenAI or Groq — without it Whisper invents text on silence (e.g. a website address). 0 = off, 1 = always (also for KB_AI_TRANSCRIBE_URL). |
KB_CHAT_HLAS_MAX_S | 300 | Longest voice note recorded in the assistant, in seconds (the browser stops recording there; an attached audio file is limited by its size only). |
KB_CHAT_MAX_AUDIO_MB | 3 | Largest accepted recording in MB (5 minutes of Opus ≈ 1.2 MB). |
KB_AI_HLAS_VAHA | 2 | How many turns of the hourly cap one voice-note turn uses (transcription + reply). |
KB_AI_PDF_VAHA | 2 | How many turns of the hourly cap one turn with an attached PDF uses (the assistant only receives the page text; merging and splitting PDFs run in the browser and cost nothing). |
Drawing pictures
The assistant draws illustrations, banners and pictures for presentations (see Pictures from the assistant). Without these settings drawing is off and the buttons do not appear.
| Variable | Default | What it does |
|---|---|---|
KB_IMAGE_PROVIDER | (empty) | openai = your own service with the standard OpenAI Images API (POST …/images/generations); api = the killBottleneck AI service from KB_AI_URL / KB_AI_TOKEN; none = off. |
KB_IMAGE_TOKEN | (empty) | API key of the image service. Required for openai; without it drawing stays off. |
KB_IMAGE_URL | (empty) | Base address of the service. For openai the default is https://api.openai.com/v1. |
KB_IMAGE_MODEL | gpt-image-1-mini | openai only: the model name. The service must return a JPEG (the app asks gpt-image models for it itself). |
KB_IMAGE_TEXT | (empty) | 1 allows pictures with readable text (the Text in the image field). |
KB_AI_GEN_VAHA | 2 | How many messages of the hourly cap (KB_AI_MAX_PER_HOUR) one picture uses up. |
KB_OBRAZEK_KREDITY | (empty) | Fixed price of a picture in AI credits. Empty = the model's reference price. 0 = pictures cost no credits and the weekly credit quota does not stop them. |
KB_OBRAZKY_TYDEN | (empty) | Weekly cap of pictures for the whole instance (from Monday). Empty or 0 = no cap. The daily-summary banner does not count. |
KB_SUMAR_EMAIL_MAX | 100 | How many morning summary e-mails the instance sends per day. |
Access and sign-in
When you need it: an instance reachable from the internet (the registration key) and Google sign-in.
| Variable | Default | What it does |
|---|---|---|
KB_SETUP_CODE | (empty) | Instance registration key. When set, every registration requires it. Empty = anyone who knows the address can register. The first account registered is always the administrator. |
KB_RATE_LIMITS | 1 | Server-side rate limits per client IP: sign-in 20 attempts / 60 s, record creation 20 / 5 s, 300 API requests / 10 s. They slow down password guessing. 0 = off. |
KB_TRUSTED_PROXY_HEADER | (empty) | Behind a reverse proxy (Caddy, nginx — see HTTPS) the limits would otherwise count the proxy's IP and the whole company would share one bucket. Set the header the proxy fills with the client's IP, typically X-Forwarded-For. Without a proxy leave it empty — the instance must not trust a header the client can forge. |
KB_GOOGLE_CLIENT_ID | (empty) | Google OAuth client ID. Empty = the "Sign in with Google" button is not shown. |
KB_GOOGLE_CLIENT_SECRET | (empty) | Google OAuth client secret. |
KB_GOOGLE_PICKER_API_KEY | (empty) | Enables picking attachments straight from Google Drive. Needs the OAuth client above plus the "Google Picker API" enabled in the same Google Cloud project. Files picked this way are stored as links — they never leave Drive. |
Set a registration key before you expose the instance
On a machine reachable from the internet, an empty KB_SETUP_CODE means anyone who finds the address can create an account.
E-mail (SMTP) is not configured here — it lives in the PocketBase admin UI, see Configuration → E-mail.
Automations
Only needed if you actually use automations on goals.
| Variable | Default | What it does |
|---|---|---|
KB_PUBLIC_URL | (empty) | Public address of this instance, sent to the agent as callback_url so it can report back. Any address the agent can reach works — on a self-host a LAN address is fine. When unset, the "Application URL" from the PocketBase admin UI is used, which after installation is http://localhost:8090 — an agent on another machine would then call itself. The agent registry in the app shows the effective address and warns about localhost. Since v0.79 the same address also goes into the OAuth metadata of /mcp and into /agent-setup.md; a localhost value is treated as unset and the address the request came in on (Host, X-Forwarded-Host, X-Forwarded-Proto) is used instead. Behind a reverse proxy that does not send X-Forwarded-Proto (Caddy does), set KB_PUBLIC_URL=https://… explicitly, otherwise the instance announces itself as http:// and MCP clients refuse OAuth. |
KB_AGENT_TIMEOUT_MIN | 90 | How many minutes an automation may run before the watchdog marks it failed. |
KB_ALLOW_PRIVATE_WEBHOOKS | (empty) | 1 allows agent webhooks to target private networks (10.x, 192.168.x, localhost). Disabled by default. |
KB_PRIVATE_WEBHOOK_HOSTS | (empty) | The narrower, safer variant: a comma-separated list of host:port that may be a webhook target even on a private network (e.g. n8n.lan:5678); every other private address stays blocked. Compose does not pass it through — set it via docker-compose.override.yml (box at the top). |
Why private webhooks are off by default
Without that guard, the server can be pointed at your internal network and used to scan it. Turn it on only when the automation target (n8n, for instance) genuinely runs on the same LAN.
Limits and instance mode
| Variable | Default | What it does |
|---|---|---|
KB_FILES_MB | (empty) | Cap in MB for uploaded attachments across the whole instance. Empty = no limit (the self-hosting default — it is your disk). 0 = uploading disabled, attachments can only be added as links. |
KB_PAGES | 1 | 0 turns off assistant pages (HTML artifacts): tools, the panel tab and public /p/… links. |
KB_PAGES_MAX | 100 | How many pages one user may have (Cloud Start 20). |
KB_PAGE_KB | 300 | Maximum size of one page in kB (a single HTML file without attachments). |
KB_PAGE_NUM_PREDICT | 12000 | Output-token cap for writing a page (Cloud Start 8000); a long page means thousands of tokens, a local model takes minutes. |
KB_PAGE_TIMEOUT | 280 | Seconds for one model call while writing a page. |
KB_AI_PAGE_VAHA | 3 | Weight of writing a page in the hourly AI limit (like an image). |
KB_HOSTED | (empty) | 1 marks an instance that runs at a provider alongside other customers. The instance administrator then may not point the AI service into a private network, and the check for new versions is off. On your own server leave this empty — a local Ollama on the LAN is the normal setup there. |
KB_ENCRYPTION_KEY | (empty) | Exactly 32 characters. Encrypts the API key an administrator of a hosted instance stores in the Own model or API key section (it sits in the database only encrypted). Without it the own model cannot be turned on. Provisioning generates it for hosting; on your own server it is not needed (AI is configured in Administration → AI features there). Never change it on a running instance — the stored key would become unreadable. |
KB_SHARE_INVITE_DAILY_CAP | 20 | How many shared-project invitations (to addresses without an account) one user may send per day. An address gets at most one per project. |
KB_SHARE_INVITE_INSTANCE_CAP | 50 | Daily cap of these invitations for the whole instance — protects the mail quota. |
KB_NOTIFY_EMAIL_DEFAULT | (empty) | Notification e-mails are off by default and driven by per-user preferences. Set to 1 to keep the old "e-mail on until the user turns it off" behaviour after an upgrade. |
KB_REPORT_TO | (empty) | Address that bug reports and ideas from the app are sent to. Empty means the feature does not exist on this instance: the menu item is not shown and the route returns 404, so nothing ever leaves. Set your own address to collect reports from your users — the reporter's address goes into Reply-To, so you can answer straight from your inbox. Requires working SMTP. |
Notifications
The defaults are sane. Change them if notices are too noisy, or if an automation of yours legitimately produces more than the cap.
There is no "unlimited"
0 is not a magic value here — it means the cap is reached immediately. Raise the number instead of zeroing it.
| Variable | Default | What it does |
|---|---|---|
KB_NOTIFY_DIGEST_HOUR | 8 | Hour of the daily e-mail digest (0–23, local TZ). |
KB_NAVRAT_MAILY | 1 | Come-back e-mails for users who have not signed in for a while (needs SMTP). 0 turns them off. |
KB_NAVRAT_DNY | 3,7,14,30 | Ladder of days without sign-in after which a come-back e-mail goes out — one e-mail per step, only the highest reached step, silence after the last one until the next sign-in. |
KB_NAVRAT_HODINA | 9 | Hour of come-back e-mails (0–23, local TZ). |
KB_NAVRAT_MAX_DENNE | 10 | Maximum come-back e-mails per instance per day (the rest wait for the next day). |
KB_REMINDER_CATCHUP_H | 48 | Catch-up window for timed reminders (hours, 0–720). After an outage, reminders whose time is older than this are only logged, not sent — so restoring an old backup does not flood the bell with meetings that already happened. Younger missed reminders are sent right after start. |
KB_NOTIFY_DAILY_CAP | 50 | Maximum in-app notices per recipient per day. Above the cap the individual rows are replaced by one growing summary ("+N more") — nothing is silently lost. |
KB_NOTIFY_EMAIL_DAILY_CAP | 10 | Maximum notification e-mails per recipient per day. Above the cap e-mails are dropped (the in-app notice still appears). |
KB_NOTIFY_COALESCE_MIN | 10 | Notices for the same recipient arriving within this many minutes are merged into one message. |
First sign-in
What a new account and a new instance see the first time — described in the Quick start.
| Variable | Default | What it does |
|---|---|---|
KB_UVODNI_MAPA | 1 | Create the two starter projects (tour + trial project) for every new user and the default shared calendars Company and Time off for the first administrator. 0 = new accounts and the instance start empty. |
KB_PURPOSE_ASK | 1 | Ask the first admin What will you use killBottleneck for? (company / family / just myself) on first login. 0 = never ask (defaults to company). Off automatically when KB_UVODNI_MAPA=0. 0 also switches off the "Connect your AI agent" dialog. |
KB_START_RELAX | (empty) | On app start the assistant panel opens by itself, once per browser tab. 1 also starts the aquarium beside it (relax without a countdown), 0 starts neither. |
KB_AGENT_SETUP_ASK | 1 | Show every user the "Connect your AI agent" dialog once after their first sign-in (one line to paste into Claude Code / Codex / Cursor, see MCP). 0 = never show it; it stays available under user menu → Connect AI agent. ⚠️ The shipped docker-compose.yml does not pass this variable through yet — it has no effect in .env; set it via docker-compose.override.yml (box at the top). |
Updates and versioning
| Variable | Default | What it does |
|---|---|---|
KB_UPDATE_CHECK | 1 | The signed-in user's browser asks the GitHub API whether a newer release exists; the About dialog then offers a link. The instance itself sends nothing anywhere. 0 turns the check off. |
KB_UPDATE_REPO | (empty) | Where releases are read from. Empty = the official repository. Set it only for your own fork. |
KB_UPDATE_PRERELEASE | 0 | 1 = the check also offers pre-releases (release candidates, -rc). With the default 0 it offers stable releases only. |
KB_VERSION | dev | Build argument, not an .env variable — pass it on the command line: KB_VERSION=$(git describe --tags --dirty) docker compose up -d --build. Left at dev, the update check is not offered. |
No telemetry
The update check runs in the user's browser against GitHub. The instance never phones home, so nothing about your installation reaches us.
Related
- Configuration — the decisions rather than the table
- Updating — what changes between versions
- HTTPS and a reverse proxy —
KB_PUBLIC_URL,X-Forwarded-Proto

