Skip to content
Yttri Docs

Manifest & API

yttri-plugin.json is the plugin’s single declarative contract. It is validated before install and before every run; any ambiguity means rejection.

Minimal manifest

Section titled “Minimal manifest”
yttri-plugin.json
{
  "manifestVersion": "1",
  "id": "acme.my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "sdkVersion": "^1.0.0",
  "yttriVersion": ">=0.80.0",
  "runtime": {
    "kind": "js_ts_v1",
    "entry": "dist/index.js"
  },
  "permissions": [
    {
      "domain": "secrets",
      "access": "write",
      "reason": "Store an API token"
    },
    {
      "domain": "network",
      "access": "read",
      "hosts": ["api.acme.com"],
      "reason": "Call the service API"
    }
  ],
  "capabilities": {
    "tools": [
      {
        "name": "acme_ping",
        "description": "Check the service.",
        "sideEffect": "read_only",
        "requiredCapability": "network"
      }
    ]
  }
}

Permissions

Section titled “Permissions”
  • domain — one of the capability domains: notes, tasks, projects, mail, calendar, contacts, documents, recordings, meetings, finance, search, integrations, accounts, editor, ui, mcp, agent, background, notifications, secrets, or network. An unknown domain rejects the whole manifest.
  • access: read | write — defaults to read; write covers read.
  • hosts is required for network. Use hostnames without a scheme or path; wildcards such as *.acme.io are supported.
  • reason is shown to the user at install time, so write it for humans.

Capabilities

Section titled “Capabilities”
  • tools — AI-agent tools: name, description, sideEffect (read_only | mutating | external), and requiredCapability.
  • jobs — manual background jobs or scheduled jobs with a cron expression.
  • settings — a settings schema (string | number | boolean | select). Yttri generates the form and exposes values through host.settings.getAll(). Store tokens only in host.secrets, not in settings.

What executes today

Section titled “What executes today”

The system is fail-closed, so an honest status matters. Today, third-party plugins can execute the notes, tasks, search, calendar, contacts, and projects domains (read and create), documents, mail, and meetings (read-only), accounts (the plugin’s connected-account registry), agent (assistant observations, SDK 1.1), plus secrets and network through helpers.

Limits inside those domains: calendar.create writes only to the local Yttri calendar — plugins get no external sync (CalDAV, Google, EWS); contacts.create does not reach CardDAV; documents, mail and meetings are read-only. Most domains expose no delete or update operations.

Other domains are accepted by the manifest, but calls into them return “operation not implemented”. Custom UI and editor extensions are unavailable to third parties: the js_ts_v1 contract has no host.ui or host.editor, so a third-party plugin’s capabilities.ui and capabilities.editor never render.