Install it

Kanban Toolkit is free software, and it is the same application however you run it: the same routes, the same SQLite schema and the same server as the Cloudflare build. One Node process, one file, a directory of static pages — no service in between, and nobody to ask.

One command, if you have Docker

git clone https://github.com/malcolmbastien/kanbantoolkit kanbantoolkit
cd kanbantoolkit && docker compose up -d

That builds the image, creates the database on a volume, applies the migrations and answers on http://localhost:8787/app. The port is bound to loopback: a reverse proxy is the way in, which is the next section of this page. docker compose down stops it and keeps the work; down -v does not.

Or three commands, if you would rather see the parts

git clone https://github.com/malcolmbastien/kanbantoolkit kanbantoolkit
cd kanbantoolkit && npm ci && npm run build
PORT=8787 DB_PATH=./kanbantoolkit.db STATIC_DIR=./dist npm run server

This is what the image does, in the open: a clone, a build, a process. The build writes the site and the app into dist/; the first start applies the schema migrations and leaves you a database file. There is no account to create first and no key to paste.

What happens on the first run

• The migrations run — inside a transaction, at start, before the first request is answered.
• The workspace is created, named by the installation (WORKSPACE_NAME, default Kanban Toolkit).
• The first person to sign in administers it — the instance and its one workspace. Everybody after them arrives by invitation.

What you take on

This is what self-hosting means rather than a caveat: the machine, and the four jobs that come with it.

• TLS. Kanban Toolkit does not terminate it. A proxy does, with a certificate, and PUBLIC_URL tells the server what that address is — which is also what makes the session cookie secure.
• Updates. You pull, build and restart. A release that adds a migration applies it at boot, and the server refuses to start rather than serve a database it does not understand.
• Backups. One file, copied somewhere else, on a schedule — and a restore you have actually run once. The copy is npm run backup; it takes a consistent snapshot while the server keeps running.
• Support. There is nobody on a rota. The help page and the documentation are the ones written for this software, and they are the ones this instance is running.

What it reads

Everything is configuration, and everything has a default that works:

• PORT — the port to listen on. Defaults to 8787.
• DB_PATH — the SQLite file. Defaults to ./kanbantoolkit.db; in the image, /data/kanbantoolkit.db.
• STATIC_DIR — where the built site and app are. Defaults to ./dist.
• WORKSPACE_NAME — what the team is called. Set it before the first sign-in.
• PUBLIC_URL — the address the outside world uses. Behind a proxy, the https one.
• LIVE — set it to 0 to switch the live channel off; the app then polls the same feed.
• ERROR_SALT — mixed into the hash of a reporter's address before it is stored. Set a secret.

The sign-in providers are optional, and an instance with none still runs: the board works, and the app says in words that it has no way in configured rather than drawing a button that cannot work. Every variable, with its default and what an unset one does, is in the documentation.

The honest limits

• One instance, one team. A deployment is a workspace. There is no second workspace to switch to, because there is no service above this one.
• The file is the database. One SQLite file, in WAL mode. Do not run two processes against it: the failure is corruption, not slowness.
• No horizontal scale. Scaling out would mean Postgres behind the same interface — a port, not a setting. One instance serves a team comfortably.
• The live channel is one process. A socket server in the Node process, or a Durable Object on Cloudflare. With neither, the app polls the same feed and nothing else changes.
• No hosted backups, and no hosted support. The file is yours, the schedule is yours, and the person who answers when it breaks is you.

There is no reduced edition and nothing to unlock: no plan, no seat count, no objective the free version withholds. Everyone runs the whole application, because there is nothing to sell.

Keeping it up

Upgrading is a backup, a pull, a rebuild and a restart. The migrations run at boot and print the schema version they reached; a migration that fails stops the process rather than guessing. Restoring is the same obstacle in the other direction: stop, put the file back, start — and the command checks the restored database's integrity and says what it restored, not just that a file moved.

npm run backup -- backup ./kanbantoolkit.db ./backups
# … upgrade, and if it goes wrong:
npm run backup -- restore ./backups/kanbantoolkit-2026-10-24T02-00-00.db ./kanbantoolkit.db --force

A restore you have never run is a hope. The documentation has the drill, and the test suite runs one on every push.

The licence

Kanban Toolkit is free software under the GNU Affero General Public License, version 3 or later. Read it, change it, run your changes — for yourself, or for a team, for nothing. The one thing it asks is the point of the licence: a modified version, run for other people over a network, offers them its source.

Where to go next

This page is the short version on purpose. The documentation lives with the code, so it is always the version you are running:

• Install, in full — the systemd unit, the health check, and what the first run writes.
• In a container — the volume, backups taken inside it, upgrading, and what SQLite means.
• Configure — every environment variable, its default, and what an unset one does.
• TLS and the proxy — Caddy and nginx, the headers, and the socket.
• Upgrade — what a release does to your database, and how to go back.
• Backup and restore — the copy, the schedule, and the drill that proves it.
• Connect an agent — the MCP tools, both transports, and the token an agent acts with.
• Identity — signing in through an issuer, and provisioning the team from a directory with SCIM.

The index is the front door to the rest — the architecture, the API, the data model. The demo is the whole product with no install at all, and the support address is in the footer of every page.