Documents that several people edit at the same time.
Two people typing in the same paragraph should both keep their words. This service is what makes that true in Kern: it merges everyone's edits, keeps the result, and hands it to whoever opens the document next.
It owns no data of its own. It authenticates the editor against core. It asks whichever module owns the document whether this person may read or write it. Then it merges the edits and stores the result.
Goal: start collab on your own machine and connect an editor to it.
You need:
- Node 24 and pnpm 10.
- A Postgres 18 database.
Most people should run the whole platform from the
umbrella repository instead. There, pnpm setup && pnpm infra && pnpm dev starts collab with everything it talks to.
pnpm install
cp .env.example .envSet DATABASE_URL in .env to your Postgres database.
pnpm devThe service creates its own database tables the first time it starts.
Expected result: migrations applied, then the service listens on port 4300 at path /collab.
Goal: serve collaborative documents from more than one process, behind an ordinary load balancer.
Set VALKEY_URL on every instance. The self-host, Coolify and cloud compose files already do.
Expected result: each instance logs collab service listening with clustered: true.
The instances then relay edits and presence to each other through Valkey, and take a lock before writing a document down. A plain round-robin proxy is enough — you do not need session affinity, sticky sessions, or a consistent hash on the document name.
Without VALKEY_URL the service is one honest process. Two of those are two different documents,
and whoever lands on the wrong one loses their edits.
If two Kern deployments share one Valkey, give each of them its own COLLAB_REDIS_PREFIX. Every
channel and lock is <prefix>:<documentName>, so one prefix means one set of documents.
One thing stays per-instance: collab.document.presence reports the connections on whichever
instance answered the call, not on all of them. Nothing in Kern calls it yet.
A document name says everything the service needs:
ws:<workspaceId>:<module>:<type>:<id>
The name tells the service which workspace to check, and which module to ask about access. A module
answers by exposing a collab.access procedure. A module that does not answer falls back to plain
workspace membership, which keeps documents usable while that module is still being built.
- Nothing is saved on every keystroke. Merged state is written after edits settle: two seconds of quiet, or fifteen seconds at the latest.
- Search does not read the merged document. A plain-text snapshot is published periodically as
collab.document.updated, so a module can index the prose without decoding the merge structure. - A deleted document leaves a tombstone. The prose goes at once; the row stays, holding only the name and timestamps. Another instance may still have the document open, and without the tombstone its next write would put the prose straight back.
Read CONTRIBUTING.md and CLAUDE.md.
AGPL-3.0-only. This repository is part of the Kern product. The Kern framework you build modules against is Apache-2.0 — see LICENSING.md.
Kern — one place for your team's work: issues, conversations, documents and people. Open source, self-hosted. kernaio.com · github.com/KernAIO