plugins.*
Plugin host RPC methods
plugins.* and the canonical plugin.* namespace are the two surfaces of the runtime plugin host. Both are registered in HandlerRegistry::new() (lines 287-310 of src/gateway/handlers/mod.rs), so they are always present regardless of whether the MCP manager is up.
plugins.*is the legacy namespace — kept for backward compatibility with older clients.plugin.*is the canonical singular namespace;plugin.installclassifies its source server-side (marketplace / git URL / local path /.zip) and routes accordingly.
For everyday users, the unified extensions.* façade is preferred. plugins.* / plugin.* are the underlying plugin backends (kind Plugin in the extensions catalog).
plugins.* Methods (legacy)
plugins.list
List every loaded plugin and its status.
Request: no params.
Response: { "plugins": [ ...PluginInfo... ] }. Each row carries name, version, description, enabled, path, capability counts (skills_count, commands_count, agents_count, hooks_count, mcp_servers_count), and a status of loaded / disabled / overridden / error (with an error field on failure).
plugins.install
Install a plugin from a Git URL.
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | yes | Git URL (https://, git@, or git://); the repo name is derived as the last path component and used as the on-disk plugin directory |
Response: { "plugin": { ...PluginInfo... } } on success; INVALID_PARAMS when the URL yields an unsafe directory name, the destination exists, or validation fails; INTERNAL_ERROR on a git2::Repository::clone failure.
plugins.installFromZip
Install one or more plugins from a base64-encoded zip archive.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | string | yes | Base64-encoded zip bytes |
Response: { "installedNames": [] } (the handler does not enumerate extracted names; use plugins.list to refresh).
plugins.unload
Unload a previously loaded plugin and remove its directory. The runtime is torn down BEFORE the directory is deleted so a services.stop or transient MCP server can still run on shutdown.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Plugin id (must be a single normal path component — no .., no /) |
Response: { "ok": true }.
plugins.load
Parse a manifest from a directory and load the plugin into the runtime (Node.js / WASM).
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Path to the plugin directory containing aleph.plugin.json or package.json with an aleph field |
Response: { "pluginId": "<id>", "name": "<name>", "kind": "Mcp|Wasm|Static" }.
plugins.unload
Reverse of plugins.load: unregisters the plugin from the runtime. Tools and hooks may still appear in the registry; use plugins.unload to remove the directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
pluginId | string | yes | Plugin id |
Response: { "ok": true }.
plugins.enable
Remove the .disabled marker so the plugin is re-discovered on the next scan.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Plugin id |
Response: { "ok": true }.
plugins.disable
Create the .disabled marker and tear down the runtime (services + transient MCP servers).
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Plugin id |
Response: { "ok": true }.
plugins.callTool
Invoke a tool that was registered by a loaded plugin.
| Parameter | Type | Required | Description |
|---|---|---|---|
pluginId | string | yes | Plugin that registered the tool |
handler | string | yes | Handler function name |
args | object | no | JSON arguments forwarded to the handler |
Response: { "result": <plugin-defined JSON> } on success; -32001 (Command not found) if no plugin-registered command with handler exists, or the call belongs to a different plugin.
plugins.executeCommand
Execute a slash command that was registered by a plugin. The handler looks up the command in the plugin's commands/ markdown (stored as a SkillRegistration with skill_type = Command).
| Parameter | Type | Required | Description |
|---|---|---|---|
pluginId | string | yes | Plugin that registered the command |
commandName | string | yes | Command name (no leading slash) |
args | object | no | JSON arguments forwarded to the handler |
Response: the DirectCommandResult (content, data, success) serialised as JSON.
plugin.* Methods (canonical, singular)
plugin.list
Same as plugins.list. Response: { "plugins": [ ...PluginInfo... ] }.
plugin.install
Unified install entry. Classifies source server-side and dispatches to the marketplace installer (bare name) or the git-clone installer (URL / path / git@…).
| Parameter | Type | Required | Description |
|---|---|---|---|
source | string | yes | Bare name → marketplace; anything with /, ., or : → git |
url | string | fallback | Legacy alias for source; source wins when both are present |
scope | string | no | user (default) / project / local |
Response: marketplace path returns { "ok": true, "name", "scope", "installed_at" }; git path returns the same shape as plugins.install.
plugin.update
Upgrade an installed plugin in place.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Plugin name |
marketplace | string | no | Disambiguates which marketplace to use |
scope | string | no | user (default) / project / local |
force | boolean | no | Re-install even if the version is unchanged |
Response: { "ok", "name", "scope", "updated", "from" (previous version), "to" (new version | null) } or { "ok", "name", "scope", "updated": false, "version" } when the latest is already installed.
plugin.uninstall
Same shape as plugins.uninstall (legacy plural form is also available).
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Plugin id |
Response: { "ok": true }.
plugin.enable / plugin.disable
Same shapes as plugins.enable / plugins.disable. Response: { "ok": true }.
plugin.load / plugin.unload / plugin.reload
| Method | Parameter | Description |
|---|---|---|
plugin.load | path | Parse and load a plugin from a directory; returns { "pluginId", "name", "kind" } |
plugin.unload | pluginId | Unload a runtime plugin; returns { "ok": true } |
plugin.reload | pluginId | Hot-reload: re-parse manifest, re-register capabilities; returns { "ok": true, "pluginId" } |
plugin.callTool / plugin.executeCommand
Same shapes as plugins.callTool / plugins.executeCommand (pluginId, handler / commandName, args).
plugin.marketplace.*
Marketplace source management. All four methods registered.
| Method | Parameter | Description |
|--------|-----------|-----------|---|
| plugin.marketplace.list | none | List registered marketplaces (built-in + user) |
| plugin.marketplace.add | source (required), name (optional) | Add a local or github marketplace; persists to [plugin_marketplaces] |
| plugin.marketplace.update | name (optional) | Refresh the index cache for one or all marketplaces |
| plugin.marketplace.remove | name (required) | Remove a marketplace and persist |
| plugin.marketplace.install | name (required), marketplace (optional), scope (optional) | Install a plugin from a named marketplace |
See Also
- Methods Reference -- All currently registered namespaces
- Extensions Store -- The unified
extensions.*façade - extensions.* -- The wrapper for the same backends