Headless kits: no page, no window

Run a kit’s native engine with no window to open, edit, render and save files on servers, in batch jobs and in tests, from code or from an agent. Free, no key.

Every kit has a native executable, kition-<kit> (for example kition-note), that opens, edits, renders, and saves its documents with no window. The SDK release carries them for macOS (arm64, x64), Linux (arm64, x64) and Windows (x64), each in its platform's bundle under bin/<platform>/ with kition-kits and kition-kits-mcp, and names every file's SHA-256 and the kit version it answers (Distribution). They can also be built from each kit's repository (cargo build --release -p kition-<kit>).

They speak the Kit Process Protocol, version 2, on the headless surface (a private socket or named pipe, a fresh token per launch): the kit never sees a path, and reads and writes files only through its host, by handle. You rarely drive that yourself:

  • From any language: kition-kits serve runs the kits for one workspace folder and takes requests by path, as JSON lines on its standard input and output (hosts.md, with examples in Python, Node and Go).
  • From Node: openHeadless(binary, file, options) in @kition/script/node (Script), on kition-kits serve: the object model, commands(), execute(), save(), saveAs().
  • From an agent: kition-kits-mcp launches the executables for you (Agents (MCP)).
  • As your own host: a host that keeps files elsewhere than a folder speaks the protocol to each kit and serves its files.* (hosts.md).

Rules a host keeps (host contract, engine contract):

  • Files are confined to the workspace: nothing outside it, nothing hidden, no link out of it.
  • A kit writes a file only when asked to save, and a save commits only while the file is the version the kit read (file_conflict otherwise); a read-only open refuses writes.
  • Failures carry a stable reason (KitProtocolError.reason, object-model BatchError).

Finding the executables: kition-kits serve and kition-kits-mcp find kits the same way. In an SDK bundle, --kits-dir kits is all they need: each kit's kit.json is in kits/<kit>/ and its executable in bin/<platform>/. Otherwise --kit <path> (repeatable) or KITION_KIT_<KIT>_BINARY names an executable, whose kit.json is the nearest one above it that names it; one whose file name no kit.json names is asked which kit it is (kit.initialize), and one that is no kit known stops the program with an error naming the path and the kits known. A kit found without one takes the kition-<kit> beside the program or on the PATH. A kit with no executable is named on standard error; --help lists every option. An executable that reports another kit.version than its kit.json (a stale build) is refused when it starts, and the agent's tool calls on that kit answer unavailable naming the executable, both versions, and what to do (H11): bump kit.json's version and rebuild, or install the matching package. Headless use is free, on your machine or your servers, and needs no licence key: only collaboration is paid.

Drafts without an editor: an agent's draft: true edits stay in the workspace's .kition/drafts/ until a person merges them (Agents (MCP)). A kit whose executable opens replicas (model.open) keeps a replica fork there, whose comparison lists the objects the draft created, changed, and deleted; the others keep a copy of the file.

Kition kit platform: engine contract (engine contract 2), host contract, KitAgent 1.4 (A1–A4, the headless Kit Process Protocol).

From kition-sdk docs/sdk/headless.md, where the snippets are tested.Source on GitHub