Quick start
killBottleneck is free to self-host, with API and MCP. Everything you need is Docker (with the Compose plugin) on an x86-64 machine. There is no cloud account to create and nothing to register.
Run it
git clone https://github.com/tengolabs/killbottleneck.git
cd killbottleneck
cp .env.example .env # optional — the defaults are fine
docker compose up -d --buildThe first start takes a few minutes — the frontend is being built. killBottleneck then runs at http://SERVER-IP:8090; colleagues on the same network just open that address in a browser. The one value worth setting in .env right away is TZ (e.g. Europe/Prague) — without it the daily summaries and reminders run in UTC.
From now on always with --build
The app is baked into the image. After any change — new code or an .env variable — it is docker compose up -d --build; a plain restart keeps the old build running. See Updating.
Create the first account
Open the address and register. A fresh instance says so in its title: Set up your instance — The first account becomes the administrator. Everyone else can then register themselves, or the administrator invites them from Organization settings — an invitation creates an account with a temporary password to hand over.
If the machine is reachable from the internet
Registration is open by default, so anyone who knows the address could create an account. Set KB_SETUP_CODE in .env before you expose it — every registration then requires that key.
What you see after the first sign-in
- What will you use killBottleneck for? — Company or team, Family and friends or Just for myself. The starter projects and the default shared calendars Company and Time off are prepared from the answer.
- Connect your AI agent — one line to paste into Claude Code, Cursor or Codex. Without an agent, or not sure what it is, close it with the big Close button; it is always available under the menu by your name → Connect AI agent (see MCP server).
- Two starter projects — a tour of the app and a trial project where you tick off your first step.
All three can be switched off in .env (KB_PURPOSE_ASK, KB_AGENT_SETUP_ASK, KB_UVODNI_MAPA) — see Environment variables → First sign-in.
Check it is really up
docker compose ps # the killbottleneck service should be "running"
docker compose logs -f killbottleneck # startup log, including the superuser link
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8090 # expect 200Where the data is
In the ./pb_data folder next to docker-compose.yml — an SQLite database plus uploaded files. It lives on the host, not inside the container, so rebuilding or removing the container does not lose anything. Read Backup and restore before you rely on that.
What next
| Draw your first map | First map |
| Put it on a domain with HTTPS | HTTPS and a reverse proxy |
| Turn on AI and the assistant | Configuration → AI |
| Let people sign in with Google | Configuration → Sign in with Google |
| Send invitation e-mails | Configuration → E-mail |
| Drive it from code | REST API |
| Connect an AI assistant | MCP server |

