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

{
  "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

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

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

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), plus secrets and network through helpers.

Other domains are accepted by the manifest, but calls into them return “operation not implemented” for now. Custom UI and account connectors are not yet available to third parties.