Plugins

Plugins are runtime artifacts that extend SOIT with packaged capabilities. A plugin can export tools, MCP servers, skills, workflow nodes, or a mixed set of capability artifacts. Plugin is the public lifecycle boundary: skills and MCP servers do not have separate install, version, or release lifecycles — they are plugin artifacts.

When to use plugins

Use plugins when a workspace needs repeatable, governed installation of external tools, internal integrations, workflow nodes, or MCP-backed capability bundles.

Plugin package format

A plugin ships as a zip with a manifest, a spec, and exported artifact files:

manifest.json
spec.json
files/
  skills/<skill_name>.json
  mcp/<server_name>.json
  tools/<tool_name>.json
  nodes/<node_name>.json

• spec.json must validate against the plugin spec schema; plugin_type is one of skill, mcp, tool, workflow_node, or mixed.
• spec.exports declares the artifacts: tool refs like tool:http:ticket_create, node refs like node:tool:health_check, plus skill and MCP server declarations.
• manifest.json carries enabled: true|false (restart-safe) and release metadata.

Install and lifecycle

• POST /api/v1/plugins/package?mode=auto uploads a zip: it installs new plugins, upgrades on version change, and returns a conflict when the same name and version already exist (use mode=reinstall only after user confirmation).
• Enabling, disabling, upgrading, and uninstalling run projectors that create or archive the plugin-owned artifacts — skills, MCP servers, tools, and workflow nodes are projected into the runtime, never hand-edited.
• Versions are immutable with digest and signature; publish and rollback append to the plugin release ledger.
• On startup, the runtime loader reloads all enabled installed plugins into the in-process registry.

Runtime registry and tool routing

Exported tools register in the kernel registry. When an agent or workflow calls a tool_ref, the tool router resolves the spec from the registry and dispatches to the right adapter; unknown refs fall back to raw HTTP tool invocation. Runtime introspection is available at GET /api/v1/plugins/runtime/tools, and POST /api/v1/plugins/runtime/reload re-syncs the registry.

API and UI surfaces

• API prefix: /api/v1/plugins — list by plugin_type, query versions, releases, installations, artifacts?artifact_kind=..., and capabilities?kind=...
• Runtime introspection: /api/v1/plugins/runtime/tools
• Web route: /plugin (workbench with one-click package upload, upgrade, and uninstall)

Related pages

• MCP and Skills — the plugin-owned artifact model.
• Plugin Development — how to build a plugin package.