Plugin Manifest Reference

manifest.yaml is the authoritative description of a plugin — identity, runtime executables, capabilities, webhooks, config schema, and optional UI bundle. Kandev parses and validates it before any plugin code runs. See Authoring a plugin for the build workflow and Plugins for install/operate.

Annotated example

id: "kandev-plugin-slack"                    # ^[a-z0-9][a-z0-9._-]*$
api_version: 1                               # must be 1 (the only supported value)
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.78.0"                 # optional

capabilities:
  events: ["task.created", "task.state_changed", "agent.completed"]
  api_read: ["tasks", "agent_profiles"]      # gates the Host data-reader RPCs
  api_write: ["tasks"]                       # reserved, no Host RPC enforces this yet
  state: true
  secrets: true

webhooks:
  - key: "slack-events"
    description: "Slack Events API webhook"
    method: "POST"                           # informational only, not enforced

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 }
  required: ["bot_token", "default_channel"]

ui:                                           # optional native frontend plugin
  bundle: "/ui/bundle.js"                    # root-relative
  styles: ["/ui/plugin.css"]                 # optional, root-relative

Field reference

ui.pages is declarative manifest metadata only. A native bundle's runtime nav items, icons, and per-route title-bar chrome (registerNavItem, registerRoute's options.topbar) are a separate JS SDK surface with no manifest.yaml field — see Authoring a plugin.

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): each entry must be one of tasks, sessions, workspaces, workflows, agent_profiles, repositories. Declaring a resource grants the matching Host accessor (Tasks(), Sessions(), Workspaces(), Workflows(), AgentProfiles(), Repositories() — see Authoring a plugin); calling an accessor for an undeclared resource returns gRPC PermissionDenied. capabilities.api_write reserves the same resource names for a future write path — no write RPC exists yet, so declaring it currently has no effect.

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 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.*).

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.