applet.json is the single source of truth for an applet’s surface. Every capability it uses is declared here and shown to the user at install time. There are no hidden capabilities.

Minimal manifest

{
  "schemaVersion": 2,
  "runtime": "sidecar",
  "id": "@my-org/notes",
  "version": "0.1.0",
  "name": "Notes",
  "author": "My Org",
  "scopes": ["projectDb:read", "projectDb:write", "system:sidecar"],
  "methods": [
    { "name": "@my-org/notes.list", "permission": "projectDb:read", "handler": "backend" }
  ],
  "tools": ["@my-org/notes.list"],
  "frontend": { "entry": "dist/index.js" }
}

Required fields

Field	Type	Notes
schemaVersion	integer	2 for current applets
id	string	@<author>/<slug>, lowercase, one slash
name	string	Human-facing applet name
author	string	Publisher name
scopes	string[]	Declared capabilities (type:scope); see Permissions & Scopes
frontend.entry	string	Path to the entry JS, usually dist/index.js

Common fields

Field	Type	Notes
version	string	Semver, per applet, independent of the bundle version
runtime	string	"sidecar" for a Node subprocess (requires system:sidecar)
description	string	One-sentence user-facing copy
deleteMessage	string	Optional warning shown before a resource is deleted; use it to explain unlink-only behavior or data that remains on disk
agent_instruction	string	LLM-facing capability statement; what the tool can do
resourceTypes	string[]	Resource type names this applet owns
icon	string	lucide-react icon name
color	string	Hex color
category	string	Grouping in the Add picker
published	boolean	false hides the applet from the production Add picker (dev tools)
methods	object[]	Method declarations; see below
tools	string[]	Subset of method names exposed to agents
outboundUrl	string[]	HTTP allowlist, e.g. ["*"] or specific hosts
httpProfile	object	Authenticated HTTP template (baseUrlTemplate, auth)

Delete confirmation copy

Use deleteMessage when deleting a resource needs applet-specific context. The host always shows its standard irreversible-action warning, then renders this message in every shared resource deletion flow. Omit the field when the standard confirmation is sufficient.

{
  "deleteMessage": "If this Docs Applet uses an external path, deleting it only unlinks that folder from this project. The external files stay in place."
}

For project-relative folderPath values, the confirmation can also offer to remove the resource’s files. Absolute external paths are never removed by the host, so deletion only unlinks the resource.

Method declarations

Each entry in methods[] declares one method. The name is the canonical applet-method name and must match the defineMethod name in code.

{
  "name": "@my-org/notes.add",
  "category": "notes",
  "permission": "projectDb:write",
  "handler": "backend",
  "defaultEnabled": true,
  "paramsSchema": { "type": "object", "properties": { "title": { "type": "string" } } },
  "returnsSchema": { "type": "object" }
}

Field	Notes
name	@<author>/<slug>.<verb> - one dot, single camelCase verb, no suffix
permission	The scope required to call it
handler	"backend" (Node sidecar) or "frontend" (webview)
category	Optional grouping for the method list
defaultEnabled	Whether the method is enabled by default; gate sensitive methods to false
paramsSchema / returnsSchema	JSON Schema for params and returns

Tools

tools[] is the subset of method names exposed to agents. A method must be in both methods[] and tools[] for an agent to call it.

"tools": ["@my-org/notes.add", "@my-org/notes.list"]

See Agent Tools.

Sub-applets

An applet can declare sub-applets that mount under a parent (for example the WordPress applets under a site). Relevant fields: parentApplet, subPath, subLabel, subIcon, subOrder, pairedOnly, requiresPlugin.

Naming rule

The method name is the same everywhere: in applet.json::methods[], in tools[], in the frontend call ctx.methods["@<author>/<slug>.<verb>"](...), and in the defineMethod registration. One canonical name, no aliases. See Method Architecture for why.