Self-host Kanzo, one kanban board for you and your agents

Create the VM#

On your computer (pick another name if my-kanzo is taken):

ssh exe.dev new --name=my-kanzo
ssh my-kanzo.exe.xyz

Everything else runs on the VM.

Install Kanzo#

Kanzo's installer puts the program in ~/.cargo/bin, the one place it can update itself:

curl -LsSf https://github.com/emanuele-em/kanzo/releases/download/v0.3.0/kanzo-installer.sh | sh
. ~/.cargo/env
kanzo --version

Expect kanzo 0.3.0. Keep it running as a systemd user service, started at boot even when no one is logged in:

kanzo service install
sudo loginctl enable-linger exedev

The first run creates ~/kanzo, with the board in kanzo.db and settings in config.toml. Kanzo listens on 127.0.0.1:4242 only; leave it there.

Put it behind the exe.dev proxy#

Kanzo refuses requests addressed to any name but localhost and pages from any origin but its own http:// one, to stop other websites from reaching it through your browser. So nginx takes exe.dev's proxy traffic on port 8000, does that check against the VM's HTTPS address instead, and passes the request on as a local one. This replaces the image's default site:

sudo tee /etc/nginx/sites-available/kanzo >/dev/null <<'EOF'
server {
    listen 8000 default_server;
    listen [::]:8000 default_server;
    server_name _;
    client_max_body_size 32m;
    location / {
        # exe.dev's proxy signs people in. Refuse pages from other sites,
        # then hand Kanzo a local request, which is all it accepts.
        set $same_site 0;
        if ($http_origin = "") { set $same_site 1; }
        if ($http_origin = "https://$host") { set $same_site 1; }
        if ($same_site = 0) { return 403; }
        proxy_pass http://127.0.0.1:4242;
        proxy_http_version 1.1;
        proxy_set_header Host localhost:4242;
        proxy_set_header Origin "";
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}
EOF
sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -sf /etc/nginx/sites-available/kanzo /etc/nginx/sites-enabled/kanzo
sudo nginx -t && sudo systemctl enable --now nginx && sudo systemctl reload nginx

Check it#

As exe.dev's proxy reaches it: the board, a write from the board's own page, a write from another site's page, and MCP:

H="Host: $(hostname).exe.xyz"; J='Content-Type: application/json'
curl -s -o /dev/null -w 'board %{http_code}\n' -H "$H" http://localhost:8000/
curl -s -o /dev/null -w 'same site %{http_code}\n' -H "$H" -H "$J" \
  -H "Origin: https://$(hostname).exe.xyz" -d '{"slug":"setup-check"}' http://localhost:8000/api/projects
curl -s -o /dev/null -w 'other site %{http_code}\n' -H "$H" -H "$J" \
  -H 'Origin: https://example.com' -d '{"slug":"nope"}' http://localhost:8000/api/projects
curl -s -o /dev/null -w 'mcp %{http_code}\n' -H "$H" -H "$J" -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}' \
  http://localhost:8000/mcp
curl -s -o /dev/null -w 'cleanup %{http_code}\n' -X DELETE http://localhost:4242/api/projects/setup-check

Expect 200, 200, 403, 200 and 200.

Back up nightly#

This script copies the board with sqlite3 .backup (safe while Kanzo and agents write), checks the copy, adds the settings and pasted images, and keeps the 14 newest:

mkdir -p ~/bin ~/backups
cat > ~/bin/kanzo-backup <<'EOF'
#!/bin/bash
# Back up ~/kanzo to ~/backups/kanzo-<time>.tar.gz. Keeps the 14 newest.
set -euo pipefail
umask 077
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
sqlite3 "$HOME/kanzo/kanzo.db" ".backup '$work/kanzo.db'"
[ "$(sqlite3 "$work/kanzo.db" 'PRAGMA integrity_check')" = ok ]
cp "$HOME/kanzo/config.toml" "$work/"
[ -d "$HOME/kanzo/images" ] && cp -r "$HOME/kanzo/images" "$work/"
out="$HOME/backups/kanzo-$(date -u +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$out.part" -C "$work" .
mv "$out.part" "$out"
ls -1t "$HOME"/backups/kanzo-*.tar.gz | tail -n +15 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/bin/kanzo-backup

Run it nightly, around 03:30 UTC:

sudo tee /etc/systemd/system/kanzo-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up the Kanzo board to ~/backups

[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/bin/kanzo-backup
EOF
sudo tee /etc/systemd/system/kanzo-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up the Kanzo board nightly

[Timer]
OnCalendar=*-*-* 03:30:00 UTC
RandomizedDelaySec=15m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now kanzo-backup.timer

Make one now and check that it opens, in a scratch directory:

backup=$(~/bin/kanzo-backup)
rm -rf /tmp/restore-check && mkdir /tmp/restore-check
tar -xzf "$backup" -C /tmp/restore-check
sqlite3 /tmp/restore-check/kanzo.db 'PRAGMA integrity_check; SELECT count(*) FROM projects;'
rm -rf /tmp/restore-check

Expect ok and a number of projects. Copy ~/backups off the VM now and then; otherwise the VM's disk holds the only copy.

On the VM, ~/bin/kanzo-backup backs up now and prints the archive's path. To copy the backups to your computer:

scp 'my-kanzo.exe.xyz:backups/kanzo-*.tar.gz' .

To restore one, on the VM, stop Kanzo, set the current board aside, and unpack:

backup=~/backups/kanzo-20261102-033012.tar.gz
systemctl --user stop kanzo
mv ~/kanzo ~/kanzo.before-restore-$(date +%s)
mkdir ~/kanzo && tar -xzf "$backup" -C ~/kanzo
systemctl --user start kanzo

On a new VM, follow Set up by hand first, then copy the archive over with scp and restore it the same way. Delete ~/kanzo.before-restore-* once you're happy.

Kanzo can also keep the board in a private git repository of yours (kanzo sync). That's meant for carrying a board between computers you use one at a time, not for a board several computers use at once.

Back up first. Then, on the VM:

kanzo update

It installs the latest release over ~/.cargo/bin/kanzo and restarts the service. The board's sidebar offers new versions too, with one click. Kanzo is pre-1.0 and releases often; read the release notes before updating a board you rely on.

On the VM, Kanzo's status and log, and nginx's:

systemctl --user status kanzo --no-pager
journalctl --user -u kanzo -n 50 --no-pager
sudo tail -n 20 /var/log/nginx/error.log

kanzo does not answer requests from other sites. The request reached Kanzo without going through nginx, for example at https://my-kanzo.exe.xyz:4242/. Use https://my-kanzo.exe.xyz/.

A plain 403 Forbidden from nginx. A page from another site, or an address other than https://my-kanzo.exe.xyz, tried to change the board. A custom domain needs its own if ($http_origin = ...) line.

An agent gets 401 or an HTML login page. No valid token reached exe.dev. Check the header name, the Bearer before the token, and that the token is for this VM and hasn't expired.

nginx won't start. Something else listens on port 8000: sudo ss -ltnp | grep ':8000' shows what. Stop it, or move it to another port, then sudo systemctl restart nginx.

502 Bad Gateway. Kanzo isn't running: check its status and log above, then systemctl --user restart kanzo.

The agent says to pass project. Over HTTP, Kanzo can't tell which repository the agent is in. Name the project in your request, or ask the agent to call list_projects.