Self-host Kanboard
A small, sturdy kanban board that signs your team in with exe.dev.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe.dev/deploy/kanboard/prompt.txt | ssh exe.dev new --prompt=/dev/stdinKanboard is a kanban board and lightweight issue tracker: projects, columns, swimlanes, tasks with comments, subtasks, attachments and due dates, a calendar and a Gantt view, automatic actions, and a JSON-RPC API that covers nearly all of it. It's PHP and SQLite, idles at a few tens of megabytes, and has looked the same for years. That's the point: it's finished software that keeps working.
On an exe.dev VM, Kanboard sits behind exe.dev's HTTPS proxy, private until you share it. Kanboard can take its sign-in from a reverse proxy, so this setup uses your exe.dev login as the Kanboard login: you are the admin, and anyone you share the VM with is signed in the first time they open it. Nobody manages Kanboard passwords. Agents on the VM, or anywhere with a VM token, create and close tasks through the API.
What you get#
- Kanboard 1.2 at
https://my-kanboard.exe.xyz/, restarted after a reboot, with SQLite in~/kanboard/data. - exe.dev login as Kanboard login: the owner is a Kanboard admin, and anyone the VM is shared with gets an account on first visit. No passwords, and Kanboard's default
adminaccount removed. - An API token in
~/kanboard/kanboard.env(mode 600) and a~/kanboard/kbhelper, checked by creating, commenting on and closing a task as theagentuser. - Nightly backups of the database and attachments in
~/kanboard/backups.
What's running, and where
https://my-kanboard.exe.xyz/
The board, for you and anyone you share the VM with, signed in by exe.dev
https://my-kanboard.exe.xyz/jsonrpc.php
The JSON-RPC API, for agents with an exe.dev VM token and the Kanboard API token
Deploy with Shelley#
Click Deploy and Shelley will set up Kanboard on a new VM, then check that it works. No config-file wrangling required.
Prefer a terminal?
curl -fsSL \
https://exe.dev/deploy/kanboard/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhat Shelley is told
Set up Kanboard on this VM by following the exe.dev recipe at https://exe.dev/deploy/kanboard.md?via=deploy from top to bottom.
The recipe's example VM name is my-kanboard. This VM's name is the output of `hostname`: use it wherever the recipe writes my-kanboard. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- Kanboard 1.2 at `https://my-kanboard.exe.xyz/`, restarted after a reboot, with SQLite in `~/kanboard/data`.
- exe.dev login as Kanboard login: the owner is a Kanboard admin, and anyone the VM is shared with gets an account on first visit. No passwords, and Kanboard's default `admin` account removed.
- An API token in `~/kanboard/kanboard.env` (mode 600) and a `~/kanboard/kb` helper, checked by creating, commenting on and closing a task as the `agent` user.
- Nightly backups of the database and attachments in `~/kanboard/backups`.
Read the whole recipe, closed details included, and follow "Install by
hand" in order, skipping VM creation; the walkthrough above it is for
the owner. If the reflection integration doesn't return the owner's
email, ask the owner for the email they sign in to exe.dev with. Never
send a made-up X-ExeDev-Email header: Kanboard creates an account for
every address it sees. Don't make the VM public. Check the agent steps
in "Let agents work the board" with a scratch project, then delete that
project. Don't run Restore or Update. Finish with the board's URL, how
to share it (`ssh exe.dev share add`), and the "Let agents work the
board" section.
Finish with the URLs I should open.
Also at /deploy/kanboard/prompt.txt. The recipe it follows is /deploy/kanboard.md.
Open your board#
Open https://my-kanboard.exe.xyz/ and sign in to exe.dev if asked.
Kanboard opens on your dashboard, signed in as your exe.dev email, with
admin rights. There's no Kanboard password to set.
- Choose New project, name it, and Save.
- Press + in the Backlog column to add a task, then drag it across the board.
- Open a task to add comments, subtasks, attachments or a due date.
Bring your team#
On your computer, share the VM with each teammate's email:
ssh exe.dev share add my-kanboard alice@example.com
exe.dev emails them an invitation. When they open
https://my-kanboard.exe.xyz/ and sign in to exe.dev, Kanboard creates
their account (a normal user, named after their email). Then, in your
project, open Permissions and add them: Kanboard shows people only
the projects they're members of. ssh exe.dev share add my-kanboard team
shares with your whole exe.dev team.
To take access away, run ssh exe.dev share remove my-kanboard alice@example.com. Their Kanboard account stays, so their name stays on
what they wrote, but they can't reach the board. You can also disable
the account under Users.
Let agents work the board#
Kanboard's JSON-RPC API takes an
application token, which setup put in ~/kanboard/kanboard.env, and
~/kanboard/kb wraps it: kb <method> '<json params>'. Things an agent
does are signed by a Kanboard user called agent.
On the VM#
Shelley, Claude Code or Codex on this VM can use kb directly. Try it
yourself, on the VM:
cd ~/kanboard
agent=$(./kb getUserByName '{"username":"agent"}' | jq .result.id)
project=$(./kb createProject '{"name":"API demo"}' | jq .result)
./kb addProjectUser "{\"project_id\":$project,\"user_id\":$agent}"
task=$(./kb createTask "{\"project_id\":$project,\"title\":\"Try the API\",\"creator_id\":$agent}" | jq .result)
./kb createComment "{\"task_id\":$task,\"user_id\":$agent,\"content\":\"Done from the API.\"}"
./kb closeTask "{\"task_id\":$task}"
./kb getTask "{\"task_id\":$task}" | jq -c '.result | {title, is_active}'
Each call prints "result": an ID, or true. false usually means a
missing permission: like people, the agent user can only create and
sign tasks in projects it's a member of, so addProjectUser (or the
project's Permissions page) comes first. The last line shows
"is_active":0: the task is closed. Closed tasks are hidden from the
board, so open API demo (under Project management: you aren't a
member of it), choose List, and search status:closed to see it
with the agent's comment. Then remove the project (Remove in the
project's menu) or keep it to play with.
Or just ask Shelley:
Use ~/kanboard/kb (Kanboard JSON-RPC) to file a task in project Website for each TODO in the README, created by the agent user (add it to the project first). Then list the open tasks in that project.
The application token can do everything the API can, across all
projects. Keep kanboard.env private, and see
Troubleshooting to rotate the token.
From your computer or another VM#
The API is behind exe.dev's proxy too, so a remote agent needs two things: an exe.dev VM token for the proxy, and the Kanboard token. Create the VM token on your computer:
ssh exe.dev ssh-key generate-api-key --vm=my-kanboard --label=kanboard-agents --exp=90d
Then, with both tokens (cat ~/kanboard/kanboard.env on the VM shows the
Kanboard one):
curl -sS https://my-kanboard.exe.xyz/jsonrpc.php \
-H "X-Exedev-Authorization: Bearer exe1.paste-vm-token-here" \
-u "jsonrpc:paste-kanboard-token-here" \
-d '{"jsonrpc":"2.0","method":"getAllProjects","id":1}'
The proxy checks and removes X-Exedev-Authorization; Kanboard checks
the -u credentials. An agent with no shell on the VM can make the same
calls with any HTTP client.
Keep your board#
Tasks, comments and attachments live in ~/kanboard/data. A nightly
timer copies them to ~/kanboard/backups. Keep a copy off the VM,
with the token file. On your computer:
scp -r my-kanboard.exe.xyz:kanboard/backups my-kanboard.exe.xyz:kanboard/kanboard.env .
For updates or hiccups, ask Shelley, or open the instructions below.
The nuts and bolts#
Happy with what Shelley set up? Stop here. Below are the steps it followed, and maintenance for later.
Install by hand
Create the VM#
On your computer (pick another name if my-kanboard is taken):
ssh exe.dev new --name=my-kanboard
ssh my-kanboard.exe.xyz
All remaining commands run on the VM, as exedev.
Write the settings#
Kanboard's admin will be the VM owner's exe.dev email, which the reflection integration knows. The API token is generated here. Both go in one file only you can read:
sudo systemctl enable --now docker.service
mkdir -p ~/kanboard && cd ~/kanboard
owner=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r '.email // empty')
echo "Kanboard admin: ${owner:?no owner email; set owner=you@example.com and rerun}"
if [ ! -f kanboard.env ]; then
(umask 077; printf 'REVERSE_PROXY_DEFAULT_ADMIN=%s\nAPI_AUTHENTICATION_TOKEN=%s\n' \
"$owner" "$(openssl rand -hex 32)" > kanboard.env)
fi
ls -l kanboard.env
The admin line should show the email you sign in to exe.dev with. If the
reflection integration is missing, set owner= to that email yourself
and rerun the block. kanboard.env should be -rw-------.
Start Kanboard#
Usernames are exe.dev emails, but Kanboard lets everyone rename their own account. A teammate could rename theirs to a colleague's email before that colleague's first visit, and keep reading it with a personal API token. A tiny plugin lets only admins change usernames. Kanboard's Logout can't sign you out of exe.dev (it just shows an empty page), so it's hidden:
cd ~/kanboard
mkdir -p data plugins/ExeLogin
printf "<?php\ndefine('DISABLE_LOGOUT', true);\n" > data/config.php
cat > plugins/ExeLogin/Plugin.php <<'EOF'
<?php
namespace Kanboard\Plugin\ExeLogin;
use Kanboard\Core\Plugin\Base;
// Usernames are exe.dev emails: only admins may change them.
class Plugin extends Base
{
public function initialize()
{
$this->container['userValidator'] = function ($c) {
return new LockedUsernameValidator($c);
};
}
public function getPluginName() { return 'ExeLogin'; }
public function getPluginDescription() { return 'Only admins can change usernames'; }
public function getPluginAuthor() { return 'exe.dev'; }
public function getPluginVersion() { return '1.0.0'; }
}
EOF
cat > plugins/ExeLogin/LockedUsernameValidator.php <<'EOF'
<?php
namespace Kanboard\Plugin\ExeLogin;
use Kanboard\Validator\UserValidator;
class LockedUsernameValidator extends UserValidator
{
public function validateModification(array $values)
{
list($valid, $errors) = parent::validateModification($values);
if ($valid && ! $this->userSession->isAdmin()) {
$user = $this->userModel->getById($values['id']);
if (empty($user) || $values['username'] !== $user['username']) {
return array(false, array('username' => array(t('Your username is your exe.dev email. Ask an admin to change it.'))));
}
}
return array($valid, $errors);
}
}
EOF
Then the container:
cd ~/kanboard
cat > compose.yaml <<'EOF'
name: kanboard
services:
kanboard:
image: kanboard/kanboard:v1.2.57
restart: unless-stopped
# Only the exe.dev proxy (which connects from 127.0.0.1) reaches Kanboard.
ports: ["127.0.0.1:8000:80"]
env_file: kanboard.env
environment:
# Sign people in with the email exe.dev's proxy puts in X-ExeDev-Email.
REVERSE_PROXY_AUTH: "true"
REVERSE_PROXY_USER_HEADER: HTTP_X_EXEDEV_EMAIL
REVERSE_PROXY_EMAIL_HEADER: HTTP_X_EXEDEV_EMAIL
# Trust that header only from Docker's gateway, i.e. from the VM itself.
TRUSTED_PROXY_NETWORKS: 172.30.80.1/32
HIDE_LOGIN_FORM: "true"
volumes:
- ./data:/var/www/app/data
- ./plugins:/var/www/app/plugins
networks:
default:
ipam:
config:
- subnet: 172.30.80.0/24
gateway: 172.30.80.1
EOF
docker compose up -d --wait --wait-timeout 180
curl -fsS http://localhost:8000/healthcheck.php; echo
Expect {"status":200,"message":"Database connection is OK"}. Kanboard
created its database in ~/kanboard/data/db.sqlite.
Add the API helper and the agent user#
kb calls the API with the application token. A fresh Kanboard also
has an admin account with the password admin; exe.dev login replaces
it, so delete it:
cd ~/kanboard
cat > kb <<'EOF'
#!/bin/sh
# kb METHOD [JSON-PARAMS]: call Kanboard's JSON-RPC API with the app token.
set -eu
token=$(sed -n 's/^API_AUTHENTICATION_TOKEN=//p' "$HOME/kanboard/kanboard.env")
curl -fsS -u "jsonrpc:$token" -H 'Content-Type: application/json' \
--data "{\"jsonrpc\":\"2.0\",\"method\":\"$1\",\"id\":1,\"params\":${2:-[]}}" \
http://localhost:8000/jsonrpc.php
echo
EOF
chmod +x kb
admin=$(./kb getUserByName '{"username":"admin"}' | jq -r '.result.id // empty')
[ -z "$admin" ] || ./kb removeUser "{\"user_id\":$admin}"
./kb getUserByName '{"username":"agent"}' | jq -e .result.id >/dev/null ||
./kb createUser "{\"username\":\"agent\",\"name\":\"Agent\",\"password\":\"$(openssl rand -hex 24)\"}"
./kb getAllUsers | jq -c '[.result[] | {username, role}]'
The last line should list only agent (an app-user). Nobody knows its
password: agents act as it through the application token.
Check the exe.dev login#
The proxy will send your email in X-ExeDev-Email. Send the same header
from the VM to create your account now and check you're an admin:
cd ~/kanboard
owner=$(sed -n 's/^REVERSE_PROXY_DEFAULT_ADMIN=//p' kanboard.env)
curl -fsS -o /dev/null -w '%{http_code}\n' -H "X-ExeDev-Email: $owner" http://localhost:8000/
./kb getUserByName "{\"username\":\"$owner\"}" | jq -c '.result | {username, role}'
curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' http://localhost:8000/
printf 'Kanboard: https://%s.exe.xyz/\n' "$(hostname)"
Expect 200, your email with "role":"app-admin", then 302 to
/login for a request without the header. Kanboard's login form is
hidden: the only way in is exe.dev.
Back up nightly#
backup.sh makes a consistent copy of the SQLite database with
VACUUM INTO, checks it, and packs it with the attachments:
cd ~/kanboard
cat > backup.sh <<'EOF'
#!/bin/sh
# Back up Kanboard: a checked copy of the SQLite database, plus attachments.
set -eu
umask 077
cd "$(dirname "$0")"
mkdir -p backups
out="backups/kanboard-$(date +%Y%m%d-%H%M%S).tar.gz"
docker compose exec -T kanboard php <<'PHP'
<?php
$copy = '/var/www/app/data/backup.sqlite';
@unlink($copy);
(new PDO('sqlite:/var/www/app/data/db.sqlite'))->exec("VACUUM INTO '$copy'");
$check = (new PDO("sqlite:$copy"))->query('PRAGMA integrity_check')->fetchColumn();
if ($check !== 'ok') { fwrite(STDERR, "integrity_check: $check\n"); exit(1); }
PHP
docker compose exec -T kanboard sh -c \
'cd /var/www/app/data && tar -czf - backup.sqlite $(ls -d files config.php 2>/dev/null); rm -f backup.sqlite' > "$out.tmp"
mv "$out.tmp" "$out"
find backups -name 'kanboard-*.tar.gz' -mtime +14 -delete
echo "$out"
EOF
chmod +x backup.sh
sudo tee /etc/systemd/system/kanboard-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up Kanboard
After=docker.service
[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/kanboard/backup.sh
EOF
sudo tee /etc/systemd/system/kanboard-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up Kanboard nightly
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now kanboard-backup.timer
sudo systemctl start kanboard-backup.service
systemctl list-timers kanboard-backup.timer
gzip -t backups/*.tar.gz && ls -l backups
The timer should list its next run, and backups should hold one
archive. Kanboard is ready: open the URL printed above.
Back up and restore
To take a backup now, on the VM:
~/kanboard/backup.sh
Each archive holds backup.sqlite (the database), files/ (task
attachments) and config.php. Kanboard's own Settings → Download the database gives
you a compressed copy of the database alone, from the browser.
Restore#
Pick an archive and put its name below. On a new VM, run Install by
hand first, copy your old kanboard.env over the new one (so the API
token carries over), and copy the archive into ~/kanboard/backups.
On the VM; this sets the current data aside rather than deleting it:
cd ~/kanboard
backup=backups/kanboard-YYYYMMDD-HHMMSS.tar.gz
tar -tzf "$backup" >/dev/null &&
sudo systemctl stop kanboard-backup.timer &&
docker compose stop kanboard &&
sudo mv data "data.before-restore-$(date +%s)" &&
mkdir data &&
tar -C data -xzf "$backup" &&
mv data/backup.sqlite data/db.sqlite &&
docker compose up -d --wait &&
sudo systemctl start kanboard-backup.timer
Open the board and check your projects. The container gives data back
to its own user when it starts.
Update
Kanboard publishes only exact version tags (v1.2.57), so updating means
changing the tag. Check the
releases for the latest
one, then on the VM, back up first:
cd ~/kanboard
version=v1.2.58 # the release you want
./backup.sh
sed -i "s|kanboard/kanboard:v[0-9.]*|kanboard/kanboard:$version|" compose.yaml
docker compose pull && docker compose up -d --wait
curl -fsS http://localhost:8000/healthcheck.php; echo
Kanboard migrates its database on the first request after an update. To go back, restore the backup you just took with the old tag.
Troubleshooting
Start with the container and its logs. On the VM:
cd ~/kanboard
docker compose ps
docker compose logs --tail=50 kanboard
- Down after a reboot? Run
sudo systemctl enable --now docker.service. - An empty login page instead of the board? Kanboard didn't accept
your email. Open the board through
https://my-kanboard.exe.xyz/, not an SSH tunnel or a public share (anonymous visitors have no email to sign in with). Kanboard trusts the header only from the gateway incompose.yaml, so if you changed the subnet,TRUSTED_PROXY_NETWORKSmust be the new gateway. Pool overlaps with other one on this address space? Another Docker network on this VM uses172.30.80.0/24. Pick a free/24and change the subnet, gateway andTRUSTED_PROXY_NETWORKSincompose.yamlto match.- You're not an admin?
REVERSE_PROXY_DEFAULT_ADMINinkanboard.envmust be exactly the email you sign in to exe.dev with. Fix it, rundocker compose up -d, and reload the page. kbprintscurl: (22) ... 401? The token inkanboard.envand the container's differ. Rundocker compose up -dafter changingkanboard.env.- Rotate the API token: replace the
API_AUTHENTICATION_TOKENline with a newopenssl rand -hex 32, rundocker compose up -d, and give agents the new token.
Frequently asked questions#
Is Kanboard free?
Yes. Kanboard is MIT-licensed, with no paid edition and no features held back; extra features come from community plugins. You pay only for your VM; see exe.dev pricing. It idles at about 30 MB of memory, so it can share a VM with other apps.
Is kanboard.io the same thing?
No. kanboard.io is an unrelated hosted product with a similar name and its own paid MCP server. This page is about Kanboard from kanboard.org, the open source project by Frédéric Guillot.
Is Kanboard still maintained?
Its README calls it "in maintenance mode": no big new features, but releases keep coming with fixes and small additions (1.2.57 came out in October 2026). That makes it a stable choice, not a fast-moving one. If you want a modern UI with cycles and pages, look at Plane.
Can someone fake the exe.dev login header?
Not from outside. exe.dev's proxy removes any X-ExeDev-* headers a browser sends and adds its own for the signed-in user. Kanboard listens only on 127.0.0.1 and trusts the header only from Docker's gateway, so only the proxy and programs on the VM itself can set it. Anyone with SSH or root access to the VM can already do anything there.
Is there an MCP server for Kanboard?
Not from the Kanboard project. Several community MCP servers wrap its JSON-RPC API, but none is maintained by Kanboard. The API is small and well documented, so agents do fine with curl and the kb helper on this page.
Why can't my teammate see my project?
Kanboard shows people only the projects they're members of. Open the project, choose Permissions, and add them after they've visited the board once (that creates their account). As an admin, you can also make them a manager under Users.
How do I sign out or switch accounts?
Sign out of exe.dev: open https://my-kanboard.exe.xyz/__exe.dev/logout and confirm. Kanboard follows whoever exe.dev says you are, so the next visit signs you in as the account you sign in to exe.dev with. Kanboard's own Logout is hidden because it can't do that.
Can I use PostgreSQL instead of SQLite?
Kanboard supports PostgreSQL and MySQL, but SQLite is its default and plenty for a team board. Stay with SQLite unless you already run a database you back up.
Updated Nov 17, 2026 · tested end to end Nov 17, 2026 · Markdown · manifest.json · Something wrong? Tell us