Kanwas: a shared context board where a team and an AI agent work on the same canvas

The problem Kanwas is aimed at: context that lives in five tools at once

The README frames the target audience by role rather than by company size. Founders are told to combine a fundraising deck, customer interviews, an MVP spec and a hiring plan on one canvas. Product managers drop interview snippets, tickets and competitor screenshots onto a board and expect a discovery readout where each claim traces back to its source. Developers pull a PM's spec, designs and research onto a canvas, turn it into an implementation plan, then run a CLI command to move the markdown into their repository.

The recurring complaint behind those scenarios is that the evidence for a decision and the decision itself end up in different places. A screenshot sits in a chat thread, a ticket in a tracker, a paragraph of reasoning in someone's head. Kanwas proposes a single surface where the agent reads the same artifacts the humans read, and where the agent's actions are visible in a shared timeline rather than hidden inside a private chat window. Marketers and sales get their own described workflows: launch planning with copy variants, and a reusable account board for research, comms history and stakeholder maps.

That is a positioning claim, not a measured outcome. The README does not present usage numbers, and none of the role descriptions come with a case study attached.

How the board actually works: canvas, Yjs server, AdonisJS backend, git-backed markdown

The repository layout is the clearest description of the architecture. There are four application directories: frontend, backend, yjs-server and cli, plus a shared package and an execenv directory. The acknowledgements name the pieces: Yjs for the collaborative data layer, BlockNote for the editor, AdonisJS for the backend framework and E2B for execution environments.

That combination explains the shape of the product. BlockNote is a block-based editor built on ProseMirror, and Yjs supplies conflict-free replicated data types, so the canvas is a shared document rather than a form that posts updates. The separate yjs-server service exists because collaborative editing needs a long-lived connection that is not the request-response backend. The docker-compose file gives the backend port 3333 and the frontend port 5173, with Postgres on 5432 and Redis on 6379 behind health checks.

The agent's tool calls streaming into a shared timeline is the part that distinguishes this from a plain collaborative editor. The README states it as a property of the product; the mechanism is not spelled out in the README itself, which points instead to docs/SYSTEM_OVERVIEW.md for the mental model. The contributing notes warn that Yjs and BlockNote have project-specific gotchas around clone semantics and transactions, which is a fair signal that the document layer is where the real complexity sits.

The CLI closes the loop. It treats a workspace as a directory of markdown files on your disk, bound to a remote workspace through a .kanwas.json file created on first pull. The README describes the storage as a git-backed markdown filesystem with full version history, which is what makes the pull-and-push workflow meaningful rather than a one-way export.

Installing Kanwas with Docker Compose and doing a first pull

The prerequisites listed are Docker with Docker Compose and an Anthropic API key, an OpenAI API key, or both. The quickstart clones the repository, copies four environment templates, and brings up the app profile. Note that the root .env.example in the repository uses GEMINI_API_KEY, so the key you fill in depends on which env file the service reads; check backend/.env.example before assuming.

git clone https://github.com/kanwas-ai/kanwas.git
cd kanwas

cp .env.example .env
cp backend/.env.example backend/.env
cp yjs-server/.env.example yjs-server/.env
cp frontend/.env.example frontend/.env

docker-compose --profile app up

The README says to open http://localhost:5173 once the stack is up. The root .env.example also asks for an APP_KEY, described as generated with node ace generate-key, plus an API_SECRET used for Yjs server authentication and an optional Slack webhook. Leaving API_SECRET at its placeholder value is the kind of thing that works locally and should not ship.

The second half of a first run is the CLI, which is a separate npm package and does not require the Docker stack to be running if you are pointing at the hosted service.

npm install -g @kanwas/cli
kanwas login
mkdir my-workspace && cd my-workspace
kanwas pull

kanwas login opens a browser tab to authorize the CLI and stores credentials globally in ~/.kanwas/config.json. The first kanwas pull is interactive: it presents a workspace picker and downloads the files into the current directory. After that, the directory is bound to the workspace through .kanwas.json, so later pulls and pushes skip the picker. To avoid the picker from the start, every command accepts --id or --name; the README gives kanwas pull --id <uuid> and kanwas pull --name "<name>" as the non-interactive forms, and notes this is what makes the CLI safe from CI or a wrapping agent.

Bulk import is the other entry point. kanwas import ./notes walks a path, picks up every .md file, skips everything else, preserves directory structure and creates the files in the chosen workspace. It accepts --name for a non-interactive target, --id for a single file, --dest to place imports under a subfolder and --overwrite to replace existing files. kanwas workspaces lists what you can write to, and kanwas workspaces --json gives machine-readable output for scripting.

Where Kanwas gets in the way

The most concrete limitation is the state of the release and upgrade story. No releases were retrieved for this repository, and the README documents no upgrade procedure, no migration path and no version compatibility policy. For a self-hosted stack with Postgres, Redis, a Yjs server and a patched editor dependency, that gap matters: the root package.json pins @blocknote/core to 0.46.0 through both a patchedDependencies entry and an overrides block, and also overrides prosemirror-view to 1.41.4. Those pins exist because the patches directory contains a patch for @blocknote/core. Anyone running this in production is maintaining a fork of an editor dependency whether they intended to or not.

The second constraint is the model API key. The quickstart requires an Anthropic or OpenAI key, and the root env template ships a Gemini key slot. Whatever the agent does, it does through a third-party API that you pay for and that sits outside the repository. There is no described local-model path.

The third is licensing ambiguity. The repository metadata reports the license as NOASSERTION while the README states Apache License 2.0 and links to a LICENSE file. That is likely a detection artifact, but it is the kind of discrepancy worth resolving by reading the LICENSE file yourself before you depend on the terms.

Finally, the collaboration model cuts both ways. Because the canvas is a Yjs document, concurrent edits are the normal case, and the contributing guide explicitly flags clone semantics and transactions as areas that trip people up. If your team wants review gates before a document changes, a CRDT-backed board is the wrong shape for that workflow.

Kanwas versus a wiki plus a chat assistant

The obvious alternative is a markdown wiki for the artifacts and a standalone coding or chat agent for the AI work. That combination is cheaper to run and has a mature upgrade story, because each half is maintained independently. The difference is where the agent's activity lives. In the split setup, the agent's reasoning happens in a conversation window that only the person who opened it can see, and the artifacts it produces get pasted into the wiki by hand. Kanwas puts the tool calls in the same timeline as the documents, so a teammate reading the board sees what the agent did to produce a claim, not just the claim.

The second alternative, for the developer workflow specifically, is to skip the board entirely and hand a spec file to a coding agent. The README addresses this directly: kanwas pull brings the markdown into your repository so you can pass it to Claude Code, Codex or another coding agent. If that is all you want, the CLI is the useful part and the canvas is overhead. Kanwas earns its place when the spec is still being argued about by people who need to see the evidence behind it.

Licence, maintenance and the cost of running your own copy

The README states Kanwas is licensed under the Apache License 2.0 and links to the LICENSE file, while the repository metadata reports NOASSERTION. Treat that as unresolved until you read the file. Apache 2.0, if that is what the file contains, is permissive and includes a patent grant, but the contributor flow here adds a Contributor License Agreement: first-time contributors are asked to sign .github/CLA.md, and a bot comments on the pull request with the signing phrase. That is a contribution-side obligation, not a use-side one, and it is not legal advice.

On maintenance, the last push to the default branch was on 2026-08-13, roughly a month before this writing, and the repository is not archived. There is no published release history to read, so the only signal about how the project moves is commit activity on master.

The operational cost is the stack itself. A self-hosted deployment runs Postgres 18, Redis 8, the AdonisJS backend, the yjs-server and the frontend, with the backend on port 3333 and the frontend on 5173. You supply the model API key. Upgrading means reconciling the pinned @blocknote/core 0.46.0 patch and the prosemirror-view 1.41.4 override against upstream, which is real work each time those dependencies move. The repository provides pnpm format and per-package lint commands, and lint-staged wires them into commits through husky, so the contribution path is at least defined.

Editorial conclusion

Adopt Kanwas if your team already works in markdown and you want an agent operating over the same evidence as the people, with the board files living in a git-backed filesystem you can pull into a repo. Skip it if you need a documented upgrade path, a published release history, or a deployment that does not depend on a third-party model API key. Before committing, clone the repository, copy the four .env.example files, run docker-compose --profile app up, and confirm the CLI round trip with kanwas pull and kanwas push against a throwaway workspace.

Frequently asked questions

Official sources

1. Issues
2. kanwas-ai/kanwas on GitHub
3. Project website
4. README