Skip to content

Get started

Introduction

What Knotworking is, how it fits together, and where to begin.

What Knotworking is

Knotworking is a workspace for a team and its AI agents: tasks and projects, a wiki, meetings and time tracking, plus modules for the rest of a business, from staff training to stock and food safety. It is free, open source and self-hosted: you run it on your own machine or a small cloud server, with a database you control.

Agents connect through the built-in MCP server with a personal API token. An agent can do only what the person who made the token can do, and less if the token leaves things out.

Architecture

A self-hosted installation is five containers, and only Caddy is exposed. The web app forwards /api/* to the API internally, so sign-in cookies stay first-party and the API is never reachable from outside.

Clients

Browser
Agent (MCP)

Exposed

CaddyHTTP or HTTPS

Internal

Web appproxies /api
MCP server/mcp, stores nothing

Core

APIpermissions, sync log

Data

Postgres
Uploadsvolume or S3
Browsers and agents reach Caddy, the only exposed container. Caddy routes pages to the web app and /mcp to the MCP server; both call the API, which alone reads and writes Postgres and uploaded files.

Every client talks to the same typed HTTP API and stays current through a shared sync log, so a teammate's change appears on your screen as they make it. The MCP server is another API client: it stores nothing and goes through the same permission checks as the web app.

Where to start

  • Quickstart: run it with Docker Compose, claim the workspace and invite people.
  • Agents and MCP: make a token and connect Claude Code or another MCP client.
  • Modules: choose what this installation runs, and who gets what.
  • Run from source: work on Knotworking itself against a seeded demo workspace.

Support

There is no support, hosted plan or service-level promise. These docs are the manual. The source is coming to GitHub soon, and bugs will be reported in its issue tracker.