---
title: "Embed a Kition editor in your app — in your page with @kition/embed, or by link with @kition/embed-server"
description: "Two ways to put a real editor in your web app over your own storage and users: mount it in your page with KitionEmbed.mount, the editor and its WebAssembly engine loading from your own CDN, with co-editing and your agent in the open document; or frame one signed iframe link from the embed server you run. Free, no key."
canonical: "https://developer.kition.ai/embed"
---

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

Embed · two ways

# Two ways to embed a kit’s editor

Two ways to embed a kit’s editor: in your page with @kition/embed, or by link with @kition/embed-server. Both are free, open source and need no key.

[**In your page**`@kition/embed`](#way-page)[**By link**`@kition/embed-server`](#way-link)

Way 1

## In your page `@kition/embed`

Mount a kit’s editor on an element of your page. It runs sandboxed from its own origin and reads and saves through your storage, for the people in your identity system.

1.  Your page**`@kition/embed`**from npm, about 90 KB
2.  Your CDN**The kit package**the editor and its WebAssembly engine, static files: about 22 MB on first open, then cached
3.  Your storage**The file’s bytes**read and written through your callbacks

No Kition server is in that path. Co-editing, if you add it, goes through a sync server.

`npm i @kition/embed`

embed.ts · after the kition-sdk README

```
import { KitionEmbed } from '@kition/embed'

const editor = await KitionEmbed.mount(element, {
  kit: {
    id: 'kit.note',
    // static files on your CDN: the editor and its WebAssembly engine
    url: 'https://cdn.example.com/kition/note-ui/',
  },
  file: { id: 'plan-2026', name: 'Plan.md' },
  storage,  // yours: read, stamp, write (versioned), create
  identity, // yours: user, users, permissions
})
```

**Choose this when**

-   Your page can run a JavaScript module, with any framework or none.
-   People co-edit, or your agent works in the document someone has open.
-   You want the editor’s events, checks and draft review in your own UI.

[Embed in your page](#in-your-page) [Quick start](https://developer.kition.ai/docs/quick-start)

Way 2

## By link `@kition/embed-server`

Run the embed server; your server signs a link for one person and one file, and your page frames it. The file is read and saved through signed callbacks to your storage.

1.  Your page**One iframe**no module, no editor code
2.  Your server**`@kition/embed-server`**the editor page and its sessions; the kit package from your CDN
3.  Your storage**Signed callbacks**HEAD, GET and PUT to your server

No Kition server is in that path either: you run the embed server, and it loads the kit package from an origin you host.

`npm i @kition/embed-server`

server.ts + page.html · condensed from docs/sdk/url.md

```
// your server: a link for one person and one file
import { signOpenToken } from '@kition/sync/openToken'
const token = await signOpenToken({ iss, aud, tenant, sub, name,
  file, version, doc_key, perms, iat, exp }, 'acme-1', privateKey)

<!-- your page: frame it -->
<iframe src="https://docs.example.com/v1/open?token=ko1.…"
  allow="clipboard-read; clipboard-write; fullscreen"></iframe>
```

**Choose this when**

-   Your page cannot run a module: a CMS, a low-code tool, a mail client’s web view.
-   One person edits a file at a time.
-   You would rather keep the integration on your server: sign a link, answer file callbacks.

[Embed by link](https://developer.kition.ai/url) [Read the guide](https://developer.kition.ai/docs/url)

See both, live

## The same note, embedded both ways

Left, this page mounts the Note editor itself; right, the by-link setup that frames the same note: the iframe and the server call that signs its link.

Way 1 · In your page `@kition/embed`

kition-note · weekly-team-sync.md

Opens weekly-team-sync.md in the real Note editor. Loads about 22 MB.

This page imports `@kition/embed` and mounts the editor on an element; the note’s bytes stay in this tab. The editor and its WebAssembly engine come from kits.kition.ai, this site’s static kits origin: in your product, your own CDN.

this page · the mount call (LiveKit.tsx)

```
import { KitionEmbed } from 'https://kits.kition.ai/embed/index.js'

// this page: the Note editor on an element
const editor = await KitionEmbed.mount(element, {
  kit: {
    id: 'kit.note',
    // this site's static kits origin; in your product, your own CDN
    url: 'https://kits.kition.ai/note-ui/',
  },
  file: { id: 'sample-note', name: 'weekly-team-sync.md' },
  storage, // read, stamp, write: the note's bytes in this tab
  locale: 'en-US',
  theme: { colorScheme: 'dark' },
})
```

Way 2 · By link `@kition/embed-server`

by link · weekly-team-sync.md

Run the same by-link setup on your machine: node examples/url-embed/serve.mjs in kition-sdk starts an integrator page, the embed server and the kit packages.

By link, your page holds one `<iframe>` and no editor code; the editor page and its saves run on the embed server you run.

your page · one iframe

```
<iframe src="https://docs.example.com/v1/open?token=ko1.…"
  allow="clipboard-read; clipboard-write; fullscreen"></iframe>
```

your server · from docs/sdk/url.md

```
import { signOpenToken } from '@kition/sync/openToken'

const token = await signOpenToken({
  iss: 'acme.app', aud: 'docs-example', tenant: 'acme',
  sub: user.id, name: user.name,
  file: 'res-42',            // your immutable file id
  version: 'v7',             // the version you open
  doc_key: 'res-42.g3',      // the file's generation: change it when the file is replaced
  perms: { edit: true, comment: true, download: true, share: false, export: true },
  watermark: null,           // or { text: 'Ann · Confidential' }
  iat: now, exp: now + 300,  // at most an hour; a few minutes is enough
}, 'acme-1', privateKey)
const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}`
```

Side by side

## In your page or by link

In your page or by link: the differences

|  | In your page `@kition/embed` | By link `@kition/embed-server` |
| --- | --- | --- |
| What you add to your page | @kition/embed and one KitionEmbed.mount(element, …) call | One <iframe src=…>; no module, no JavaScript integration |
| What you run | The kit package (static files: the editor and its WebAssembly engine) on your CDN, an origin apart from your page (and a sync server, for co-editing) | The embed server (Node 20.6 or later), and the kit packages on your CDN; your server signs the links and answers the callbacks |
| Where the editor runs | In a sandboxed frame from the kit’s origin, inside your page | On the embed server’s page, which your page frames; the kit loads from another origin |
| Files | Your StorageProvider in the page: read, stamp, write (versioned), create | HMAC-signed HTTP callbacks to your server: HEAD, GET and PUT /files/{file} with If-Match. The embed server keeps no document and creates no files |
| People and permissions | Your IdentityProvider: edit, comment or view per person and file | Signed into the link: the person, edit, comment or view, and download, export, share and a watermark |
| Co-editing | Yes, with the collaboration option: Kition Server or Kition Cloud | No: single-user, one editor per link |
| Your agent in the open document | editor.agentPort(): its edits go to a draft the person compares and merges or discards in your page | Not in the framed page: it offers no agent port and no draft review |
| Events and API | The full editor API: saved, changed, conflict, draft, presence and other events; save(), check(), the object model | Two messages to your page: ready, and saved with the new version |
| Best for | Apps that can run a module and want co-editing, agents or their own controls around the editor | Pages that cannot run a module, where one person edits one file |

Co-editing, your agent in the open document and draft review come with @kition/embed in your page; embedded by link, the editor is single-user. From kition-sdk’s [embed guide](https://developer.kition.ai/docs/embed) and [embed-by-link guide](https://developer.kition.ai/docs/url).

Way 1 · @kition/embed

## Embed in your page

One call mounts a kit’s editor on an element. The editor and its WebAssembly engine load from your CDN and run sandboxed on that origin; the file is read and saved through your storage, for your users. Works with React, Vue, Svelte, plain JS, Node, Next.js and any MCP client.

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

```
import { KitionEmbed } from '@kition/embed'

const editor = await KitionEmbed.mount(element, {
  kit: {
    id: 'kit.doc',
    // static files on your CDN: the editor and its WebAssembly engine
    url: 'https://cdn.example.com/kition/doc-ui/',
  },
  file: { id: 'project-proposal', name: 'project-proposal.docx' },
  // your StorageProvider:
  // read, stamp, write (versioned), create
  storage,
  // your IdentityProvider:
  // token, user, users, permissions
  identity,
})
```

kition-doc · project-proposal.docx

Opens project-proposal.docx in the real Doc editor. Loads about 37 MB.

### How it works

1.1

1.  Your page**KitionEmbed.mount**
    
    You pass `kit.url`, the kit package’s folder on your CDN, with the file’s id and name, your storage and your identity provider.
    
2.  Your CDN**The editor and its WebAssembly engine**
    
    The browser downloads the kit package from kit.url (about 22 MB for Note the first time, then from its cache) and runs it in a sandboxed frame of that origin; after the handshake everything travels over a private MessagePort.
    
3.  Your storage**read, stamp, write, create**
    
    Every save goes back through your StorageProvider. A write carries the version it read, so an edit made elsewhere is never written over.
    

**Host the kit package**

1.  **Download it.** Note’s is `kition-note-<version>.tgz` on [kition-note’s releases](https://github.com/KitionAI/kition-note/releases/latest); it unpacks to `note-ui/`.
2.  **Upload the folder** to your CDN, object storage or any static host, on an origin that is not your page’s.
3.  **Point `kit.url` at it.** The browser fetches the editor and the `.wasm` from there when someone opens a file.

**Why another origin:** the editor runs in a sandboxed frame of that origin, so it cannot reach your page’s cookies, storage or session. Kition hosts no kit packages for your product: they are your files, on your CDN.

**Headers on the kit origin**

-   `.wasm` as `application/wasm`.
-   A content security policy whose `frame-ancestors` names your page, and no `X-Frame-Options: DENY` or `SAMEORIGIN`.
-   CORS: the frame needs none. If your page reviews agent drafts, let it read `model/schema.json`.
-   Cache: hashed files under `assets/` for a year (`immutable`); the rest for a short time, so a new version reaches people.

The full list, with the exact policy: [embed reference, Hosting kit packages](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/embed.md#3-hosting-kit-packages).

terminal · Note’s kit package on your CDN

```
# 1. the Note kit package, from kition-note's release
curl -LO https://github.com/KitionAI/kition-note/releases/download/package-v0.1.0/kition-note-0.1.0.tgz
tar -xzf kition-note-0.1.0.tgz
# → note-ui/: index.html, assets/, engine/ (the .wasm), fonts/

# 2. upload note-ui/ to your CDN, object storage or static host,
#    on an origin that is not your page's, e.g.
#    https://cdn.example.com/kition/note-ui/

# 3. check the engine is served as WebAssembly
curl -sI https://cdn.example.com/kition/note-ui/engine/kition_note_kit_bg.wasm | grep -i content-type
# content-type: application/wasm
```

### The calls that matter

1.2

-   [`KitionEmbed.mount(element, options)`](https://developer.kition.ai/docs/embed)Mounts the editor: kit, file, storage, identity, and optional collaboration, locale, theme and ui.
-   [`storage: { read, stamp, write, create }`](https://developer.kition.ai/docs/embed)Your StorageProvider. Refuse a stale write with EmbedConflictError and answer stamp with the current version.
-   [`identity`](https://developer.kition.ai/docs/embed)Your IdentityProvider: token, user, users and permissions (edit, comment or view per person and file).
-   [`editor.ready() · editor.save()`](https://developer.kition.ai/docs/embed)Wait for the document to open; save through your storage on your own button.
-   [`editor.on('changed' | 'saved' | 'error', …)`](https://developer.kition.ai/docs/embed)Follow the document: unsaved changes, saves, and failures with a stable reason.
-   [`editor.check()`](https://developer.kition.ai/docs/embed)What the kit finds wrong with the document: { code, severity, target, message, fix? }, errors first.
-   [`editor.document(kit, { origin })`](https://developer.kition.ai/docs/script)The object model of the open document (mounted with model: true), for scripts in the page.
-   [`editor.draft.compare() · merge() · discard()`](https://developer.kition.ai/docs/embed#drafts)Review an agent’s draft in the page; merge and discard run only on the person’s click.

### A complete example

1.3

The SDK’s example page mounts the Note editor over files kept in the browser, with co-editing, its own toolbar button, a script run through the object model and an agent’s draft review.

kition-sdk · examples/embed-app/src/main.ts

main.ts

```
const editor = await KitionEmbed.mount(element.querySelector('.frame'), {
  kit: { id: found.kit.id, url: found.kit.url },
  file: { id: file.id, name: file.name },
  storage,
  identity,
  ...(settings.collab ? { collaboration: { server: settings.server, ...(room ? { room } : {}) } } : {}),
  locale: 'en-US',
  theme: { colorScheme: 'light', tokens: { '--kit-primary': '#5645d4' } },
  // The page's own button in the editor, and the person's own hides kept with the page.
  ui: {
    add: [{ id: 'example.submit', place: 'action', label: { 'en-US': 'Submit for review' }, icon: 'send' }],
    personal: { hide: hides()[found.kit.id] ?? [] },
    customize: ({ hide }) => localStorage.setItem(HIDES, JSON.stringify({ ...hides(), [found.kit.id]: hide })),
  },
  // The page edits notes through the object model too (the "Run script" button).
  model: found.key === 'note',
})
editor.on('collab', (state) => { /* status: off, connecting, online, offline */ })
editor.on('presence', (peers) => { /* who else is in the file */ })
editor.on('error', report)
// The agent's draft, for the person to review: Merge and Discard run only on their click (UI-D1).
editor.on('draft', (info) => { /* show the review bar when info.state is 'ready' */ })
saveButton.addEventListener('click', () => void editor.save().catch(report))
editor.ready().then(() => (element.dataset.ready = 'true'), (error) => { report(error); closeFile(file.id) })
```

**Its storage**

storage.ts · examples/embed-app/src/storage.ts (condensed)

```
const storage = {
  read: async (fileId) => {
    const file = files.get(fileId)
    return { bytes: file.bytes.slice(), version: `v${file.version}` }
  },
  stamp: async (fileId) =>
    files.has(fileId) ? `v${files.get(fileId).version}` : null,
  write: async (fileId, bytes, { expectedVersion }) => {
    const file = files.get(fileId)
    const current = `v${file.version}`
    if (expectedVersion !== null && expectedVersion !== current)
      throw new EmbedConflictError(fileId, current)
    files.set(fileId, { ...file, bytes: bytes.slice(), version: file.version + 1 })
    return { version: `v${file.version + 1}` }
  },
  // an export or a copy: keep it, answer { fileId, name, version }
  create: async (name, bytes) => { /* … */ },
}
```

**An agent’s draft, reviewed in the page**

docs/sdk/embed.md

```
editor.on('draft', async ({ state }) => {
  if (state !== 'ready') return hideReview()
  const { summary, before, after } = await editor.draft.compare({ maxSize: 640 })
  // created / changed / deleted objects, and PNGs of both sides
  showReview(summary, before, after)
})
// one undo step, recorded as the agent's
mergeButton.onclick = () => editor.draft.merge()
// the document stays as it is
discardButton.onclick = () => editor.draft.discard()
```

### Limits and requirements

1.4

-   Host each kit package on **an origin of its own** (your CDN), never your page’s: the frame’s `allow-same-origin` is safe only because the origins differ.
-   Serve `.wasm` as `application/wasm`, with a content security policy that allows the kit’s scripts, workers and WebAssembly, and `frame-ancestors` naming your page.
-   Your page’s policy lets the kit origin into frames (`frame-src`) and, when co-editing, its sockets reach the sync server.
-   Mount in the browser: with server-side rendering, render the element on the server and mount on the client.

-   Without `collaboration` the editor is single-user. Co-editing runs through [Kition Server or Kition Cloud](https://developer.kition.ai/collaboration).

[Try the editors in the playground](https://developer.kition.ai/playground)

[Way 2 · @kition/embed-server**Can’t run a module in your page?** Embed by link: frame one signed iframe from the embed server you run.](https://developer.kition.ai/url)

## Put a real editor in your product

Install the package, put the kit package on your CDN, mount it on an element. Or run the embed server and frame a signed link.

`npm i @kition/embed`

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