---
title: "Real-time co-editing for the Kition SDK — Kition Server and Kition Cloud"
description: "Add one option to KitionEmbed.mount and the people in your app co-edit spreadsheets, documents, slides and every other kit in real time, through Kition Cloud or Kition Server on your own machines."
canonical: "https://developer.kition.ai/collaboration"
---

> Canonical HTML: [https://developer.kition.ai/collaboration](https://developer.kition.ai/collaboration)

Collaboration · Kition Server

# Edit the same file together

Kits are single-user and free. Add `collaboration` to the mount and people co-edit in real time, with presence and comments. Real-time co-editing through Kition Server or Kition Cloud.

embed.ts · from docs/sdk/collab.md

```
KitionEmbed.mount(element, {
  kit, file, storage,
  identity: {
    user: () => ({ id: me.id, name: me.name }),
    // Asked on every connection: a fresh token from your server.
    token: async () => (await (await fetch('/api/sync-token', {
      method: 'POST',
      body: JSON.stringify({ documents: '*' }),
    })).json()).token,
  },
  collaboration: { server: 'wss://sync.kition.ai/v1/t/acme', room: docId },
})
```

kition-sheet · Sales.xlsx · 2 editing

01 · Flow

## How it works

1.  Your page**collaboration: { server, room }**
    
    Each editor of a document joins its room. identity.token is asked on every connection.
    
2.  Your server**Issues sync tokens**
    
    Short-lived tokens that name one person, the documents and the role. The sync secret never reaches a browser.
    
3.  Kition Server**kition-sync/1**
    
    The sync server for the open protocol: rooms, presence, offline edits merged when the connection comes back.
    

02 · API

## The calls that matter

-   [`collaboration: { server, room }`](https://developer.kition.ai/docs/collab)The sync server URL, and the room: pass the document id so everyone with a token for it opens the same room.
-   [`identity.token()`](https://developer.kition.ai/docs/collab)A fresh sync token from your server, asked on every connection; the editor reconnects when one expires.
-   [`identity.user()`](https://developer.kition.ai/docs/collab)Who this person is: { id, name }, shown to the others in the room.
-   [`editor.collab.state`](https://developer.kition.ai/docs/embed){ status, docId, role }: status is 'connecting', 'online' or 'offline'; docId is the room the first editor made.
-   [`editor.on('collab' | 'presence' | 'comments', …)`](https://developer.kition.ai/docs/embed)Connection changes, who else is in the file, and comment threads.
-   [`POST /api/sdk/sync-tokens`](https://developer.kition.ai/docs/collab#tokens)Your server asks Kition Console for a token with your tenant and its sync secret (Kition Cloud).
-   [`openRoom() · createRoom()`](https://developer.kition.ai/docs/script)A script on a shared document from Node, through the same room (@kition/script/node).

03 · Hosting

## Hosted or self-hosted

Kition Cloud

### We run it

Your tenant’s rooms at `wss://sync.kition.ai/v1/t/<tenant>`. Your server exchanges your tenant’s sync secret for tokens at Kition Console, with no licence key. Billed by usage, in credits.

http · docs/sdk/collab.md

```
POST https://kition.ai/api/sdk/sync-tokens
Authorization: Bearer <your tenant's sync secret, kss_…>
Content-Type: application/json

{ "tenant": "acme",
  "user": { "id": "u-42", "name": "Ann" },
  "documents": ["0192f2d4-7b1a-4c6e-9f10-3a5b6c7d8e9f"],
  "role": "editor", "ttl": 900 }
```

Kition Server

### You run it

The `kition-server` binary on your machines (Kition provides it on request; there is no public image yet), with MySQL 8 and an S3-compatible bucket. Your server signs the tokens with your own Ed25519 key, or keeps using Console’s.

kition-server.toml · docs/sdk/collab.md

```
production = true
listen = "0.0.0.0:18300"
public_url = "https://sync.example.com"

[auth]
# no Kition accounts: only your sync tokens
mode = "tokens"

# the tenant this server's sync tokens are for
[selfhost]
tenant = "acme"

# KITION1 licences, one per line (none: up to 8 co-editors)
[licence]
file = "/etc/kition/licences"

# your own key: your server signs the tokens, bound to selfhost.tenant
[[tenants.key]]
kid = "acme-sync-1"
public_key = "<base64url Ed25519 public key>"

# URL and keys from KITION_SERVER_MYSQL_URL, KITION_SERVER_S3_*
[storage]
mode = "mysql"
[storage.s3]
endpoint = "https://s3.example.com"
bucket = "kition-server"
```

-   Kition Server: free for up to 8 people, no key.
-   Kition Server: Business $3,000/yr, Enterprise $15,000/yr; Kition Cloud by usage.

The kits never need a key: files always open, edit and export. [Pricing](https://developer.kition.ai/pricing) · [Talk to us](https://kition.ai/contact)

04 · Example

## A complete example

A script on a shared document: Alice shares a small plan as a room on a development Kition Server, her script numbers every item’s title through the room, and Bob sees the new titles arrive. Neither runs a kit: each keeps a replica of the room.

kition-sdk · examples/sdk-scripts/run-room.mjs

run-room.mjs

```
import { createRoom, openRoom } from '@kition/script/node'

// Alice's plan (kit example.plan, the example's own schema), made with the Kit Data Model alone.
const { docId, shareLink } = await createRoom({
  server, token: alice, kit, schema, name: 'Plan', document: replica.snapshot(),
})

// Bob opens the room by its share link and listens.
const watcher = await openRoom({ server, token: bob, shareLink, schema })
const arrived = new Promise((resolve) => watcher.on('changed', (event) => resolve(event.origin)))

// Alice's script, on the same room: extension/script is the origin its changes carry.
const script = await openRoom({
  server, token: alice, docId, kit, schema,
  origin: { kind: 'extension', principal: 'example:retitle' },
})
const after = await titles(script, (title, index) => `${index + 1}. ${title}`)
```

05 · Limits

## Limits and requirements

-   A sync token lives 1 minute to 1 hour and names one tenant, one person, the documents it opens (`"*"` or at most 100 ids) and the role: `owner`, `editor`, `commenter` or `viewer`.
-   On Kition Cloud, rooms are private to your tenant: there are no share links.
-   Your tenant is a stable name (2 to 40 lowercase letters, digits and inner hyphens) that your rooms belong to; its sync secret stays on your server.

-   Kition Server needs MySQL 8 and an S3-compatible bucket; it is closed source.
-   The page’s content security policy lets its sockets reach the sync server (`connect-src`).
-   Embedding by link is single-user; a collaborative version is planned: [Embed by link](https://developer.kition.ai/url).

[Start with a single-user editor](https://developer.kition.ai/embed)

## Add co-editing to your editors

`npm i @kition/embed`

[Open playground](https://developer.kition.ai/playground)
