Extension Types
Compare Kunkun's plugin runtimes and choose the right one.
Kunkun supports several plugin architectures with different capabilities and isolation levels. Each command in your manifest picks exactly one mode.
Quick comparison
| Type | Runtime | UI | Node.js access | Use case |
|---|---|---|---|---|
| Custom-View | BrowserWindow | Full control | No | Complex SPAs, dashboards, existing web apps |
| Worker-View | Web Worker | React → host renders | No | Raycast-style extensions, max isolation |
| Node-View | Node.js / Deno process | React → host renders | Yes | UI + filesystem/shell/native |
| Worker-Headless | Web Worker | none | No | Background commands (browser sandbox) |
| Node-Headless | Node.js / Deno process | none | Yes | Background commands with system access |
| Service | Node.js / Deno process | none | Yes | APIs for other extensions and the AI agent |
UI plugins
Custom-View
A static SPA loaded into an isolated BrowserWindow via kunkun-ext://. You control the entire UI with any framework.
{ "name": "main", "mode": "custom-view", "main": "/", "dist": "dist", "devMain": "http://localhost:5173" }Best when you need full UI control, are converting an existing web app, or want framework-specific features. → Guide
Worker-View
React components run in a Web Worker; the host renders your component tree as native UI (see How Extensions Run). Consistent styling, strong sandbox, fast startup, no Node.js.
{ "name": "main", "mode": "worker-view", "main": "dist/App.js" }Best for Raycast-style list/form extensions. → Guide
Node-View
Same UI model as worker-view, but running in a Node.js/Deno process — so you get filesystem, shell, and native module access.
{ "name": "main", "mode": "node-view", "main": "dist/node/App.js", "runtime": "auto" }Headless commands
No UI — run logic, optionally show a toast, exit. → Guide
{ "name": "sync", "mode": "node-headless", "main": "dist/node/Sync.js" }Headless commands can also be scheduled (interval, cron) or event-triggered.
Service plugins
Declare a services[] array and your extension exposes callable, schema-validated methods that other extensions — and the built-in AI agent — can invoke through the service broker. → Guide
Runtime selection (Node modes)
For node-view / node-headless / services, Kunkun picks the runtime automatically:
| Priority | Runtime | Why |
|---|---|---|
| 1 | Deno | Best sandbox — per-domain --allow-net, scoped --allow-read/write |
| 2 | Node.js v20+ | Node permission model |
| 3 | utilityProcess | Fallback, no sandbox |
Force one with "runtime": "deno" (or "node"). See Permissions → process sandbox.
Deno is preferred for a reason
Deno restricts network access per-domain at the process level (--allow-net=api.example.com), whereas Node's model is coarser. If your extension does network I/O, Deno gives users a tighter guarantee.
Choosing
| You need… | Use |
|---|---|
| Full UI control / an existing web app | Custom-View |
| Raycast-style UI, no system access | Worker-View |
| UI and filesystem/shell/native | Node-View |
| Background work, browser sandbox | Worker-Headless |
| Background work with system access | Node-Headless |
| APIs for other extensions / AI | Service |