Repository avatar
AI Tools
v1.2.3
active

kanopy

io.github.acidvegas/kanopy

Self-hosted kanban board built for AI agents, with a built-in MCP server.

Documentation

kanopy

The self-hosted kanban board built for AI agents and the people they work with.

acidvegas.github.io/kanopy

Release Tests Docker Python 3.12+ License

Quick start · Why kanopy · Features · Connecting agents · MCP tools · Configuration

An agent filing, claiming and finishing a task

kanopy keeps your projects, todos and ideas on one board, and lets the agents you work with read and update it the same way you do. Claude Code, opencode or anything else that speaks MCP can file tasks, claim them, move them through To-Do, Doing and Done, leave progress notes and pick up where the last session left off. Every change is logged with who made it, person or agent.

It is a single Python process with a SQLite database (or PostgreSQL for bigger teams) and a plain JavaScript frontend.

Project boardTask page
ProjectTask
CalendarThemes
CalendarThemes

Screenshots use invented demo data.

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.

kanopyVikunjaPlankaJira
Self-hostedYesYesYesData Center only (paid)
MCPBuilt inBuilt in since 2.7Community serversAtlassian's cloud server

What kanopy does for agents on top of that:

  • Every change names its agent. Comments and history show the agent and the person whose token it used, like claude (brandon), so you always know who did what.
  • Claims. Moving a task to Doing claims it for that agent session. A second session that tries to start it is told who has it instead of doing the same work twice.
  • No lost edits. An agent cannot replace a description it has not read, and edit and append change one line without resending the rest. If an agent does make a mess, the last 10 versions of a description can be restored, and deleted tasks sit in a 30-day trash.
  • Cheap on tokens. Tools answer in compact text with one line per task instead of JSON. Fifty tasks come back in about 1,200 tokens.
  • Context at session start. A Claude Code hook briefs each new session on the project for the current directory and its open tasks, flagging work left in Doing.
  • Rules and limits. Agents get your working rules when they connect, can be given tokens limited to certain projects and a role, and you get a push when one finishes a task.

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

  • Ten themes, from the purple default to Dracula, Nord, Gruvbox, Catppuccin and GitHub Light
  • Works on a phone, including drag and drop
  • Markdown editor with a toolbar, preview, shortcuts and @mention autocomplete
  • Daily database backups to data/backups, newest 3 kept
  • Export a project, or everything you can see, as one JSON file (project menu, or Settings)
  • GET /health answers ok while the database responds (no sign-in; the Docker image uses it as its health check)

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.

RoleCan
ViewerRead the project and its tasks
EditorCreate and work on tasks
ManagerAlso 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

ToolDoes
list_projectsProject tree with open task counts
list_tasksTasks 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_taskFull tasks with description, links and the last 5 comments (comments for all), or an attachment's text
save_taskCreate or update any field, edit or append to the description, tick a checklist item, comment; ids updates many at once
save_projectRename or move, describe, set the local folder, archive
commentAdd a progress note
linkRelate two tasks, or remove the relation
labelsList labels, create a global type: value (admin), delete one
inboxUnread notifications
deleteA task (to the trash), or an empty project; restore brings a deleted task back

A few rules keep agents from making a mess:

  • A new project is created by filing its first task into it, so no project is ever empty
  • An agent must read a task before it can replace the whole description, so it never overwrites edits it has not seen; edit (exact text, must match once) and append need no read
  • host: labels that differ only by punctuation (host:web01 and host:web-01) are rejected
  • Moving a task to doing claims it for that agent session (by:claude(brandon)#a1b2c3 on its line, the agent's name on its card). Another session that tries to start it is told who has it, and takes over only with take=true. Each MCP connection gets its own session id, so two Claude sessions never mistake each other's work for their own

Configuration

Settings live in .env:

VariableDefaultPurpose
KANOPY_HOST127.0.0.1Address to listen on
KANOPY_PORT8000Port to listen on
KANOPY_URLPublic address when behind a reverse proxy
KANOPY_KEYOptional; stored as the admin's API token on start, for older agent configs
KANOPY_DATABASEdata/kanban.dbA postgresql://user:pass@host/db URL to use PostgreSQL instead of SQLite
KANOPY_UPDATE_CHECK10 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

KeyAction
/Focus the filter
nNew task
EscClose 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

Mirrors: SuperNETs • GitHub • GitLab • Codeberg
OCI
ghcr.io/acidvegas/kanopy:1.2.3
Install Command
docker pull ghcr.io/acidvegas/kanopy:1.2.3:undefined
Runtime: docker

Remote

streamable-http
https://{host}/mcp