Writing a plugin

A plugin is a folder with a manifest, an entry, and handlers. It registers actions into the shared pool on activation.

Shape

A plugin is a folder under bb-plugins/ with a plugin.json manifest declaring its skills (actions), an index.js entry, and handler files. Config (API keys, settings) lives in Plugin.config and is injected into handlers at runtime — never hardcode keys.

plugin.json (excerpt)

{
  "name": "my-plugin",
  "skills": [
    {
      "name": "my.action",
      "handler": "handlers/myAction.js",
      "input_schema": { "type": "object", "properties": { "x": { "type": "string" } } }
    }
  ],
  "config_schema": { "type": "object", "properties": { "api_key": { "type": "string", "secret": true } } }
}

handlers/myAction.js

export default async function myAction(input, context) {
  const apiKey = context.pluginConfig.api_key; // read config at runtime
  // ... do work, return a plain object
  return { ok: true, result: input.x };
}

Activating a plugin runs its entry code in-process. Keep activation admin-only and only ship/activate trusted code. See Security.

HTTP action plugin Self-hosting