Skip to content

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 ​

bash
git clone https://github.com/tengolabs/killbottleneck.git
cd killbottleneck
cp .env.example .env    # optional — the defaults are fine
docker compose up -d --build

The 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.

You can tell a fresh instance by its title — whoever registers first is the administrator.

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 ​

  1. 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.
  2. 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).
  3. Two starter projects — a tour of the app and a trial project where you tick off your first step.
The purpose question is asked once, to the first administrator. KB_PURPOSE_ASK=0 switches it off.

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 ​

bash
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 200
This is what a healthy start looks like. The link at the end of the log is for the PocketBase admin UI (SMTP) — you do not need it for everyday work.

Where 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 mapFirst map
Put it on a domain with HTTPSHTTPS and a reverse proxy
Turn on AI and the assistantConfiguration → AI
Let people sign in with GoogleConfiguration → Sign in with Google
Send invitation e-mailsConfiguration → E-mail
Drive it from codeREST API
Connect an AI assistantMCP server

Open source under the MIT license · © Tengo s.r.o.