Plugins

Overview

Plugins are installable capability bundles that extend what a workspace can do. They range from ambient guardrails that enforce rules automatically, to on-demand skills invoked via the Skill tool, to workflow plugins that compose skills into slash commands.

Plugins follow a two-axis model: the source (where the plugin comes from) is orthogonal to the shape (what format it takes). This means you can install a plugin from a local registry or from GitHub, and the workspace runtime figures out how to load it based on its shape.

Two-Axis Model

Sources (where)

Use GET /plugins/sources to list all registered install-source schemes at runtime.

Shapes (what)

The shape is orthogonal to the source. A github:// plugin and a local:// plugin can both be agentskills.io format. The per-runtime adapter inside the workspace handles loading at startup.

Installing a Plugin

curl -X POST http://localhost:8080/workspaces/{id}/plugins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"source": "local://molecule-careful-bash"}'

From GitHub (pinned ref required):

curl -X POST http://localhost:8080/workspaces/{id}/plugins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"source": "github://Molecule-AI/molecule-plugin-careful-bash#v1.0.0"}'

The platform resolves the source, stages the plugin files, copies them into the workspace container at /configs/plugins/<name>/, and triggers an automatic workspace restart so the runtime picks up the new plugin.

Uninstalling a Plugin

curl -X DELETE http://localhost:8080/workspaces/{id}/plugins/{name} \
  -H "Authorization: Bearer {token}"

Uninstall removes the plugin directory, cleans up copied skill directories and rule markers from CLAUDE.md, and triggers an automatic workspace restart.

Listing Plugins

Platform Registry

List all available plugins in the platform registry:

# All plugins
curl http://localhost:8080/plugins

# Filtered by runtime
curl http://localhost:8080/plugins?runtime=claude-code

Plugins with no declared runtimes field in their manifest are treated as "unspecified, try it" and included in filtered results.

Available for a Workspace

Returns plugins filtered to those supported by the workspace's current runtime:

curl http://localhost:8080/workspaces/{id}/plugins/available \
  -H "Authorization: Bearer {token}"

Installed on a Workspace

curl http://localhost:8080/workspaces/{id}/plugins \
  -H "Authorization: Bearer {token}"

Each installed plugin is annotated with whether it still supports the workspace's current runtime. This lets the canvas grey out plugins that went inert after a runtime change.

Runtime Compatibility Check

Before changing a workspace's runtime, check which installed plugins would become incompatible:

curl "http://localhost:8080/workspaces/{id}/plugins/compatibility?runtime=langgraph" \
  -H "Authorization: Bearer {token}"

Response:

{
  "target_runtime": "langgraph",
  "compatible": [...],
  "incompatible": [...],
  "all_compatible": false
}

The canvas uses this to show a confirmation dialog before applying a runtime change.

Built-in Plugins

Hook Plugins (ambient enforcement)

These fire automatically via the harness layer. No explicit invocation needed.

Skill Plugins (on-demand)

Invoked explicitly via the Skill tool during a conversation.

Workflow Plugins (slash commands)

Compose skills into repeatable multi-step workflows.

Shared Plugins

Loaded by default from the plugins/ directory at the repo root.

Platform Opt-in Plugins

Available in the platform registry (local://) but not installed by default. Add them per workspace or as org defaults as needed.

Installing molecule-medo

# 1. Set your API key
curl -X POST http://localhost:8080/workspaces/{id}/secrets \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"key": "MEDO_API_KEY", "value": "your-medo-api-key"}'

# 2. Install the plugin (triggers auto-restart)
curl -X POST http://localhost:8080/workspaces/{id}/plugins \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"source": "local://molecule-medo"}'

Or add it to org.yaml:

workspaces:
  - name: App Builder
    plugins: [molecule-medo]
    secrets:
      MEDO_API_KEY: "${MEDO_API_KEY}"

Org Template Plugin Resolution

When deploying an org template, per-workspace plugins: lists in org.yaml role overrides UNION with defaults.plugins (deduplicated, defaults first). They do not replace them.

To opt a specific default out for a given role or workspace, prefix the plugin name with ! or -:

defaults:
  plugins:
    - molecule-careful-bash
    - molecule-audit-trail
    - superpowers

workspaces:
  researcher:
    role: "Research Analyst"
    plugins:
      - browser-automation       # added on top of defaults
      - "!superpowers"           # opted out of superpowers

Result for the researcher workspace: molecule-careful-bash, molecule-audit-trail, browser-automation

Install Safeguards

Environment variables that bound the cost and security of a single plugin install:

These prevent a slow or malicious source from tying up a handler goroutine or exhausting disk space.

Supply Chain Security

The platform enforces two controls to protect against compromised or tampered plugin sources (SAFE-T1102):

1. Pinned refs (enforced)

All github:// installs must include a #tag or #sha suffix. This ensures the code you audit is exactly what gets installed — a push to the same branch cannot silently swap in different code between your review and a workspace restart.

✅  github://Molecule-AI/my-plugin#v1.2.3       (semver tag)
✅  github://Molecule-AI/my-plugin#abc1234def   (commit SHA)
❌  github://Molecule-AI/my-plugin              (→ HTTP 422)

To bypass during local development, set PLUGIN_ALLOW_UNPINNED=true in your platform environment. Do not set this in production.

2. SHA-256 content integrity (optional)

When installing from GitHub, you can provide an expected SHA-256 hash of the staged plugin tree. The platform verifies the hash before completing the install — a mismatch aborts with HTTP 422 and cleans up the staging directory.

curl -X POST http://localhost:8080/workspaces/{id}/plugins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "source": "github://Molecule-AI/my-plugin#v1.2.3",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }'

How the hash is computed: Walk all non-manifest files in the staged plugin tree, sort by relative path, concatenate as <rel-path>\x00<content>, and compute sha256.Sum256. The hash is lowercase hex.

You can pre-compute the expected hash from a clean checkout:

# In a clean clone of the plugin repo at the target ref:
find . -type f ! -name 'manifest.json' | sort | \
  xargs -I{} sh -c 'printf "%s\x00" "{}" && cat "{}"' | sha256sum

Plugin Download (External Workspaces)

External workspaces (those running outside Docker) can pull plugins as gzipped tarballs:

curl http://localhost:8080/workspaces/{id}/plugins/{name}/download \
  -H "Authorization: Bearer {token}" \
  -o plugin.tar.gz

An optional ?source=github://owner/repo query parameter lets external workspaces pull from upstream repos without the platform pre-staging them. Defaults to local://<name> when omitted.

API Reference