Documentation

Install kanopy, connect your agents and configure the board. This page is built from the README.

Quick start#

With Docker, from the published image:

mkdir -p kanopy/data && cd kanopy
docker run -d --name kanopy -p 8000:8000 -e KANOPY_HOST=0.0.0.0 -v "$PWD/data:/app/data" --user "$(id -u):$(id -g)" ghcr.io/acidvegas/kanopy

Or with Docker Compose from a checkout:

git clone https://github.com/acidvegas/kanopy && cd kanopy
cp .env.example .env
mkdir -p data
docker compose up -d

Or with a virtual environment:

git clone https://github.com/acidvegas/kanopy && cd kanopy
python3 -m venv venv
venv/bin/pip install -r requirements.txt
cp .env.example .env
venv/bin/python -m kanopy.app

Open http://127.0.0.1:8000. The first page asks you to create the admin account; everyone after that joins through an invite link.

To run it as a service, copy kanopy.service to /etc/systemd/system/, set YOUR_USER and /path/to/kanopy, then sudo systemctl enable --now kanopy.

Why kanopy#

kanopy was made for working with AI agents first. Before writing it we looked at the boards people already run: Vikunja, Planka and Jira. They are good boards built for people, and agents can reach all three today. Connecting an agent to a board is no longer the hard part. Working alongside several agents at once, without them clobbering each other or your edits, is.

kanopy Vikunja Planka Jira
Self-hosted Yes Yes Yes Data Center only (paid)
MCP Built in Built in since 2.7 Community servers Atlassian's cloud server

What kanopy does for agents on top of that:

Features#

Board and projects#

Projects form a tree addressed by path, like Code/weatherbox, and a project's board includes its sub-projects. Cards drag between To-Do, Doing and Done, onto another project in the sidebar, or onto a date in the month calendar. Each project has a markdown description panel and an activity page listing every change across it.

The Done column loads its newest 25 tasks with a button for more, done tasks archive themselves after a configurable number of days, and a bulk mode moves, labels or deletes many tasks at once. Deleted tasks stay in the trash on the Settings page for 30 days, with their comments, links and attachments, and can be restored.

Tasks#

A task carries a markdown description with clickable checklists, a priority, due date, reminder, labels, assignees, file attachments, comments and links to other tasks (blocks, subtask, related, duplicates, precedes). It opens in a side panel or as a full page at #/task/123, and #123 anywhere in text links to it. Long comment threads show the newest 30 first.

Tasks can repeat daily, weekly, monthly, yearly, every N days or on chosen weekdays. Marking one done creates the next occurrence with its checklist reset and its dates moved forward; upcoming ones show faded on the calendar.

Every task keeps a history of who changed what, including the agent's name for changes made over MCP. The text of the last 10 description edits is kept, and any of them can be restored from the history.

Search and labels#

Search matches every word across titles, descriptions and comments, with filters for project, label, assignee, priority, due date and status. The sidebar filter narrows the board and the project tree as you type (#id, text, @me, labels, team:name for projects shared with a team).

Labels use a namespace:value form. Global labels are shared and managed by the admin; a fresh install starts with a set of type: labels. Anyone can add personal labels for their own use.

Notifications#

Each person can get pushes through ntfy on their own server and topic: at reminder time, on the morning a task assigned to them is due, as a daily overdue digest, when an agent using their token finishes a task, and for mentions, assignments and activity on their tasks. Each kind has its own switch, and pushes follow each person's timezone (picked, or taken from their browser). Mentions, assignments and activity always land in the in-app inbox too. Someone with no topic set just gets no pushes.

Everything else#

Accounts and sharing#

Everyone signs in with a username and password. The admin creates single-use invite links (valid 7 days) on the Settings page.

Projects are private to whoever made them until shared with a user or a team. Sharing a project includes its sub-projects.

Role Can
Viewer Read the project and its tasks
Editor Create and work on tasks
Manager Also edit, archive and share the project

Anyone can create a team and add members by username. Admins see every project.

A team owner can give the team an https webhook URL. Every change made on a project shared with the team (new tasks, field changes, comments and deletes, on its sub-projects too) is then POSTed there as JSON: event (created, updated, commented or deleted), actor, agent, task (id, title, project, status, priority, due, assignees, labels, url), changes (field, old, new) and comment. A bulk change sends one bulk event listing its tasks instead. The URL must resolve only to public addresses (no loopback, LAN or tailnet) and kanopy connects to the exact address it checked, so DNS rebinding cannot redirect it; redirects are refused, and a key= parameter is sent as an Authorization: Bearer header. Posts go out one at a time from a queue of up to 500 (the oldest is dropped past that), and the team card shows the last failed send until one succeeds.

Connecting agents#

kanopy serves MCP at /mcp (streamable HTTP, stateless). Each agent authenticates with a personal API token from Settings, API tokens, acts as that user and sees only what they can. Without a token only the handshake and the tool list answer, so MCP directories can check the server; every tool call needs one. The X-Agent header names the agent in comments and history. A token can be limited to certain projects (and everything under them) and to a highest role: read-only, editor, manager or full access. It never gets more than its user's own role, a limited token cannot make top-level projects or use admin powers, and the agent only sees the tools it can use. Tokens reach the board only, never account or admin endpoints, so one token can never create another.

Agents get a short set of working rules on connect from agents/instructions.example.txt. Copy it to agents/instructions.txt (untracked) to describe your own project layout.

Claude Code

Add the server:

claude mcp add --transport http -s user kanopy http://HOST:PORT/mcp --header "X-Agent: claude" --header "X-Key: $TOKEN"

Add agents/hook.sh as a SessionStart hook in ~/.claude/settings.json. Each new session then starts with a briefing on the project for the current directory and its open tasks:

{
    "hooks": {
        "SessionStart": [{ "hooks": [{ "type": "command", "command": "/path/to/kanopy/agents/hook.sh" }] }]
    }
}

Link the /task command, which files a task without a proposal step:

ln -s /path/to/kanopy/agents/task.md ~/.claude/commands/task.md
opencode

Save your token to ~/.config/opencode/secrets/kanopy.token and add the server to ~/.config/opencode/opencode.json:

{
    "mcp": {
        "kanopy": {
            "type": "remote",
            "url": "http://HOST:PORT/mcp",
            "headers": { "X-Agent": "opencode", "X-Key": "{file:~/.config/opencode/secrets/kanopy.token}" }
        }
    }
}

Link the session briefing plugin (it reads KANOPY_API, default http://127.0.0.1:8000) and the /task command:

ln -s /path/to/kanopy/agents/opencode.ts ~/.config/opencode/plugins/kanopy.ts
ln -s /path/to/kanopy/agents/task.md ~/.config/opencode/command/task.md
Anything else

Any MCP client that supports streamable HTTP works: point it at http://HOST:PORT/mcp with the X-Key and X-Agent headers. For a session briefing without MCP, GET /api/context?cwd=<dir> with the X-Key header returns plain text for the project whose folder contains dir.

A client that can only launch a local command can run kanopy over stdin/stdout on the machine where kanopy keeps its database, with KANOPY_TOKEN set to an API token and KANOPY_AGENT naming the agent:

KANOPY_TOKEN=$TOKEN KANOPY_AGENT=claude python -m kanopy.stdio

MCP tools#

Tool Does
list_projects Project tree with open task counts
list_tasks Tasks filtered by project, team, labels, text (with the matching line), status, priority or due date; ready lists what can start now (todo, no open blockers); changed lists recent activity
get_task Full tasks with description, links and the last 5 comments (comments for all), or an attachment's text
save_task Create or update any field, edit or append to the description, tick a checklist item, comment; ids updates many at once
save_project Rename or move, describe, set the local folder, archive
comment Add a progress note
link Relate two tasks, or remove the relation
labels List labels, create a global type: value (admin), delete one
inbox Unread notifications
delete A task (to the trash), or an empty project; restore brings a deleted task back

A few rules keep agents from making a mess:

Configuration#

Settings live in .env:

Variable Default Purpose
KANOPY_HOST 127.0.0.1 Address to listen on
KANOPY_PORT 8000 Port to listen on
KANOPY_URL Public address when behind a reverse proxy
KANOPY_KEY Optional; stored as the admin's API token on start, for older agent configs
KANOPY_DATABASE data/kanban.db A postgresql://user:pass@host/db URL to use PostgreSQL instead of SQLite
KANOPY_UPDATE_CHECK 1 0 stops the server asking GitHub for the latest release (shown to admins in Settings)

Everything else is set on the Settings page: each person's ntfy and timezone in their account, the board's push times and auto-archive by an admin. Data, attachments and backups live in data/.

SQLite or PostgreSQL#

SQLite is the default and handles a team of dozens of people and agents on tens of thousands of tasks. PostgreSQL is there for larger boards: install its driver with venv/bin/pip install "psycopg[binary]==3.3.9" (the Docker image already has it), set KANOPY_DATABASE and restart. Daily backups to data/backups cover SQLite only; back PostgreSQL up with pg_dump.

A board moves between the two in either direction. The source is left as it was and the destination must be a new, empty database:

venv/bin/python -m kanopy.migrate data/kanban.db postgresql://kanopy:secret@localhost/kanopy
venv/bin/python -m kanopy.migrate postgresql://kanopy:secret@localhost/kanopy data/new.db

Stop kanopy while copying, then point KANOPY_DATABASE at the new database.

Live updates#

Open pages check for changes every 15 seconds and reload the board when someone else changed it, unless you are in the middle of an edit. If someone changes a description while you are editing it, saving shows their version and asks before overwriting it.

Running behind a reverse proxy

Keep KANOPY_HOST=127.0.0.1 and set KANOPY_URL to the public address, like https://kanopy.example.com. Notification and invite links then use it, the sign-in limit sees the real client address, and the session cookie is marked Secure.

server {
    listen 443 ssl;
    server_name kanopy.example.com;
    ssl_certificate     /etc/letsencrypt/live/kanopy.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kanopy.example.com/privkey.pem;
    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Keyboard shortcuts#

Key Action
/ Focus the filter
n New task
Esc Close the task, leave select mode

Tests#

The suite in tests/ covers the data layer, permissions, the MCP tools, accounts, notifications and every HTTP route. Each test runs against a fresh database in a temporary directory, and ntfy pushes are recorded instead of sent, so it never touches data/ or the network.

venv/bin/python -m unittest

To run the same suite against PostgreSQL, point KANOPY_TEST_DATABASE at a throwaway database. It is wiped before every test, so never use a real one:

docker run -d --name kanopy-pg-test -e POSTGRES_PASSWORD=test -p 127.0.0.1:55432:5432 postgres:17-alpine
KANOPY_TEST_DATABASE=postgresql://postgres:test@127.0.0.1:55432/postgres venv/bin/python -m unittest