Plugin Manifest Reference

manifest.yaml is the authoritative description of a plugin: identity, runtime executables, capabilities, webhooks, agent tools, config schema, and optional native UI or isolated web apps. Kandev parses and validates it before any plugin code runs. See Authoring a plugin for the build workflow and Plugins for install and operation.

Quick path

1. Start from the annotated example.
2. Set identity, version, and either a runtime executable or ui.web_apps. Add only the capabilities the plugin needs.
3. Add config, webhooks, events, or UI fields only when the plugin uses them.
4. Validate the manifest before packaging.

Annotated example

id: "kandev-plugin-slack" # ^[a-z0-9][a-z0-9._-]*$
api_version: 2 # use 1 or 2; v2 is recommended for new packages
version: "1.0.0"
display_name: "Slack Notifications"
description: "Post to Slack on task events, relay messages to agents"
author: "kandev"
categories: ["connector"] # connector | automation | tools | analytics
repo_url: "https://github.com/kdlbs/kandev-plugin-slack" # optional; "Repo" link in Settings > Plugins

runtime:
  type: binary # only supported value today
  executables:
    linux-amd64: server/plugin-linux-amd64
    linux-arm64: server/plugin-linux-arm64
    darwin-amd64: server/plugin-darwin-amd64
    darwin-arm64: server/plugin-darwin-arm64
    windows-amd64:
      server/plugin-windows-amd64.exe
      # any subset; the host's <goos>-<goarch> key
      # is required at install time
min_kandev_version: "0.91.1" # required for admin actions

capabilities:
  events: ["task.created", "task.state_changed", "agent.completed"]
  api_read: ["tasks", "agent_profiles"] # gates the Host data-reader RPCs
  api_write: ["tasks", "messages"] # gates Host task and message writes
  state: true
  secrets: true
  agent_invoke: true # gates Host.InvokeUtilityAgent
  auth: true # gates external (OIDC/SAML) login; see ADR 0050
  user_state: true # gates host.storage (per-user browser storage)

webhooks:
  - key: "slack-events"
    description: "Slack Events API webhook"
    method: "POST" # informational only, not enforced
    access: public # public (default) or authenticated
    max_body_bytes: 4194304 # public maximum 4 MiB; authenticated maximum 16 MiB

actions: # authenticated manifest-declared actions; some are backend-invoked
  - key: "connection.save"
    scope: "workspace" # workspace | task | repository
    access: admin # authenticated (default) | admin
    max_body_bytes: 65536 # 1 through 1048576
  - key: "repositories.inspect"
    scope: "workspace"
    max_body_bytes: 16384
  - key: "repositories.branches"
    scope: "workspace"
    max_body_bytes: 16384

repository_providers: ["acme"] # optional provider ids owned while active
reference_sources: # optional dynamic composer sources
  - source: "acme-pull-requests"
    provider: "acme"
    kind: "pull_request"
    display_name: "Acme pull requests"
    kind_label: "Pull request"

auth_providers: # login buttons (needs capabilities.auth)
  - id: "google"
    display_name: "Google"
    initiate: "login-start" # names a webhook key above; the button navigates there

config_schema:
  type: object
  properties:
    bot_token:
      {
        type: string,
        secret: true,
        title: "Bot Token",
        description: "Slack bot OAuth token",
      }
    default_channel:
      { type: string, description: "Default channel for notifications" }
    notify_on_task_created: { type: boolean, default: true }
    utility_agent:
      {
        type: string,
        format: utility-agent,
        title: "Utility Agent",
        description: "Agent used for plugin LLM calls",
      }
  required: ["bot_token", "default_channel", "utility_agent"]

agent_tools:
  - name: add_tag
    description: Add an existing tag to the current task.
    surfaces: [kanban-task]
    input_schema:
      type: object
      properties:
        tag_id: { type: string }
      required: [tag_id]
      additionalProperties: false
    output_schema:
      type: object
      properties:
        task_id: { type: string }
      required: [task_id]
      additionalProperties: false
    annotations:
      read_only_hint: false
      destructive_hint: false
      idempotent_hint: true

ui: # optional native frontend plugin
  bundle: "/ui/bundle.js" # root-relative
  styles: ["/ui/plugin.css"] # optional, root-relative
  keybindings: # optional, requires ui.bundle
    - id: "open-panel" # plugin-local: ^[a-z0-9][a-z0-9-]*$
      default: "mod+shift+j" # combo grammar, see field reference
      description: "Open the Acme panel"
      allow_in_editor: false # optional; true lets it fire while typing

Isolated web applications

An isolated web application is a packaged static app that Kandev loads in a sandboxed iframe. It does not need a backend executable. The package uses the relative ./_kandev/v1 protocol and does not receive an injected JavaScript API.

id: "acme-task-board"
api_version: 2
version: "0.1.0"
display_name: "Acme Task Board"
description: "A task board for Kandev canvases"
author: "Acme"

ui:
  web_apps:
    - key: main
      title: Task board
      entry: ui/index.html
      placements: [task-canvas, workspace-canvas]
      network_origins: [https://api.example.com]

The package contains the declared entry document and its static files:

acme-task-board-0.1.0.tar.gz
├── manifest.yaml
└── ui/
    ├── index.html
    ├── app.js
    └── styles.css

Omit runtime, base_url, and endpoints for a static web-app package. A package can declare both runtime.type: binary and ui.web_apps when its web app needs a managed backend. Use Authoring a plugin for a complete authoring path.

Field reference

Security: capabilities.auth lets a plugin assert external login identities. Grant it only to trusted plugins whose identity provider verifies email ownership; a spoofed email claim can take over an account.

ui.pages is declarative manifest metadata only and is not currently rendered by the frontend. A native bundle's runtime nav items, icons, routes, named slots, and per-route title-bar chrome (registerNavItem, registerRoute, and registerComponent) are the supported JS SDK surface with no corresponding manifest.yaml field, see Authoring a plugin.

ui.web_apps is the manifest surface for isolated static web apps. Kandev owns the host label, placement, route, and canvas controls. The web app owns the content inside its frame. It uses packaged scripts and styles, relative Kandev protocol paths, and only the capabilities and network origins that the host grants. Declare exact HTTPS origins in network_origins when the app needs external network access. Paths, credentials, wildcards, query strings, and fragments are rejected.

Static web app network origins

ui.web_apps[].network_origins is optional. Each value must be an exact HTTPS origin with no path, credentials, wildcard, query string, or fragment. Kandev reviews each declared origin as a separate grant before the app can contact it.

The runtime sets form-action 'none', so packaged forms cannot submit to an external origin. Requests to an approved network_origins value go directly from the browser. The host tears down the app iframe immediately after a release, grant, scope, archive, disable, or removal authority change, then requires a fresh runtime binding before mounting it again.

Managed vs. legacy manifests

Setting runtime.type: binary makes a manifest runtime-managed: kandev spawns and supervises the declared executable itself. A managed manifest must not set base_url or an endpoints block (health/events/ webhooks paths on a remote service); those describe the old remote/operator-hosted tier, and validation rejects a managed manifest that sets them.

A manifest with an empty runtime.type still parses as a legacy remote manifest (with base_url/endpoints instead) and passes manifest.Validate() on its own, but the installer rejects it: pkgtar .Install requires manifest.IsManaged() to be true (runtime.type: binary), so a legacy manifest can never actually be installed via POST /api/plugins/install or a filesystem sideload. The remote tier is effectively removed in practice, even though the manifest schema still recognizes its shape.

Host data API resource vocabulary

capabilities.api_read gates the read-only Host data accessors (ADR 0043, ADR 0047): each entry must be one of tasks, sessions, messages, workspaces, workflows, agent_profiles, executor_profiles, repositories. Declaring a resource grants the matching Host accessor (Tasks(), Sessions(), Messages(), Workspaces(), Workflows(), AgentProfiles(), Repositories()), or the optional pluginsdk.ExecutorProfiles(host) extension; see Authoring a plugin. Calling an accessor for an undeclared resource returns gRPC PermissionDenied. capabilities.api_write currently accepts tasks and messages. tasks enables Host.Tasks().Create and .Update; messages enables Host.Messages().Send. The host applies the same first-party task service and message-delivery path as its own UI/API, emits the normal events, stamps created rows/messages as plugin:<id>, and does not let a plugin supply that provenance. A plugin may declare a read resource without its write capability, or vice versa. Calling a write without the matching declaration returns gRPC PermissionDenied.

messages reads historical conversation content (Messages().List): one user/agent message per row (id, session_id, task_id, turn_id, author_type, content, type, created_at), filterable by session ids, task ids, a created_at time range (since inclusive / until exclusive, RFC3339), and message types. Content is sanitized; kandev-injected <kandev-system> blocks are stripped, exactly like the message.added bus event, so raw system prompts are never exposed. author_type is user or agent (there is no system author).

Config schema validation and secret fields

config_schema is not an arbitrary, purely descriptive JSON Schema; kandev validates submitted config against a specific subset of it before persisting:

• required (an array of property names) is enforced; a PATCH missing a required property is rejected.
• type (string, boolean, number, or integer) is checked against the submitted value.
• enum membership is checked when present.
• A string property with format: utility-agent is rendered as a picker of configured built-in and custom utility agents. The UI displays agent names but persists the selected agent's stable ID. Add the property to required when the plugin must always have a selection; optional fields include a Not set choice.
• A property with secret: true, or format: "password", is treated as a secret field and must be type: string (or untyped); a non-string secret is rejected. Secret values are moved into kandev's encrypted vault; GET /api/plugins/{id}/config returns the literal mask "********" in their place, and resubmitting that mask unchanged is treated as "keep the stored value" rather than overwriting it with the literal string.
• title is read by the settings-page renderer as a display label override for the property (falling back to the property name); it has no backend validation effect.

The plugin process itself always sees real, unmasked values (secrets included) via the GetConfig Host RPC; masking only applies to the operator-facing API/UI.

Event subscription vocabulary

capabilities.events entries are bus subjects (e.g. task.created) or wildcard patterns using * as a single dot-segment wildcard (e.g. task.*, agent.*, github.*). A pattern segment of * matches exactly one subject segment; every other segment must match literally; and the pattern and subject must have the same number of dot-separated segments to match at all. task.* matches task.created (2 segments each) but does not match a three-segment subject such as shell.output.<sessionId> (shell.* would not match it either; 2 vs. 3 segments).

Any subject kandev publishes on its internal event bus is a valid subscription target; this is not a closed list scoped to any one feature area. The table below groups every subject defined in internal/events/types.go by domain (some are further suffixed per-session, e.g. shell.output.<sessionId>, git.event.<sessionId>; subscribe to the literal wildcard segment count that matches, e.g. shell.output.*).

A delivered event's event_type (pluginsdk.Event.EventType) is the concrete subject it was published on, i.e. the same string your pattern matched, so a plugin subscribed to shell.output.* reads the session id off event_type as its last segment. For an unsuffixed subject that string is just the subject itself (task.created).

Event list current as of 2026-07-16; regenerate from apps/backend/internal/events/types.go if this page drifts from the code.

Runtime-managed fields (do not author these)

Once installed, kandev writes several fields onto the stored record alongside the parsed manifest. These are kandev-owned runtime state, not author-supplied manifest fields: do not include them in manifest.yaml; they have no effect there and are overwritten on install:

Related: Plugins, Authoring a plugin.