DocsPlugins

Manifest and permissions

Everything a plugin declares lives in manifest.json: what it is, where its UI is, which commands it has, and which permissions it needs.

Example

JSON
{
  "schema": 2,
  "key": "json-tools",
  "name": "JSON Tools",
  "version": "1.0.0",
  "minHost": "2.2.0",
  "description": "Format, minify and stably sort JSON.",
  "icon": "{}",
  "ui": { "entry": "ui/index.html", "mode": "iframe" },
  "permissions": ["clipboard.write", "notify"],
  "commands": [
    {
      "id": "transform",
      "title": "Transform JSON",
      "description": "Validate JSON, then format, minify or sort it by key.",
      "handler": "scripts/transform.mjs",
      "params": {
        "type": "object",
        "properties": {
          "text":   { "type": "string", "description": "JSON text to process" },
          "action": { "type": "string", "enum": ["format", "minify", "sort"] }
        },
        "required": ["text"]
      }
    }
  ],
  "contributes": { "tool": { "category": "dev" } }
}

Fields

Field Description
schema Always 2.
key Globally unique; lowercase letters, digits and hyphens; cannot be changed after creation.
name / description Name and one-line description shown in the market.
version Semantic version; each upload must be higher than the last.
minHost Minimum desktop app version; older clients will not install this version. Use 2.2.0 when you use the __kit__ SDK.
icon / cover Emoji icon; cover is a cover image path inside the package, generated automatically if omitted.
ui UI entry; mode is always iframe. Command-only plugins can omit it.
permissions Permission array (see below), shown to the user item by item at install time.
commands[] Commands. Commands with a handler are registered as AI tools; see Command scripts.
contributes.tool.category Category: efficiency / media / dev / ai / fun.
Other contributes skills (inject prompts into AI), island / panel (need the matching overlay permission), shortcuts (needs the shortcuts permission).

Permissions

PermissionCapabilityRisk
clipboard.read / clipboard.writeRead / write the clipboardMedium
notifyToast notificationsLow
ai.chatCall AI models (uses the user's credits)Medium
image.generate / video.generateGenerate images / videos with AI (uses the user's credits)Medium
web.searchWeb search (uses the user's credits)Medium
storage.localLocal KV, 5MB per pluginLow
storage.cloudCloud KV for the accountMedium
user.profileNickname and avatar (no phone number or token)Medium
fs.pickRead / write files the user picksMedium
fs.saveShow a Save As dialogLow
fs.workspaceRead / write workspace filesHigh
shell.revealReveal files in Finder / ExplorerLow
shell.openOpen links in the default browserLow
shell.openPathOpen local files or apps with the system defaultHigh
capture.screenCapture the current screenMedium
media.camera / media.microphoneCamera / microphoneHigh
overlay.island / overlay.panelIsland / floating panelMedium
shortcutsRegister global shortcutsMedium
system.statsRead CPU, memory, battery and network speedLow
system.mediaControl music playbackMedium
ocrRecognize text in images (local first, official cloud as fallback)Low
processRun programs on the user's computerHigh
net.fetch:<domain>Access a specific domain; declare each domain separatelyMedium
  • The UI bridge enforces permissions: an installed plugin calling an undeclared capability gets an error; drafts only get a warning, to make development easier.
  • Camera and microphone are refused by the host unless declared.
  • Command scripts are not limited by permissions; they run in a full Node environment. If a script uses the network, files or child processes, you must still declare net.fetch:<domain>, process and so on, so users can confirm at install time and reviewers can check.
  • Plugins with high-risk permissions need a usage explanation when listed, and reviewers check the code.

Where to store data

Option Permission Notes
Local KV storage.local 5MB per plugin, kept across reinstalls.
Cloud KV storage.cloud Isolated per user and plugin; 64KB per item, 1MB total, 60 requests per minute. Writable only after the plugin is listed; use local KV while it is a draft.
Your own backend net.fetch:<domain> The install dialog shows the domains accessed; the platform is not responsible for that data.