Plugins¶
A plugin is a folder with a manifest, plugin.json, and a program that speaks MCP over stdio. It can add tools, hooks, decision providers, backends, page panels, skills and in-engine hooks. TandemApp installs it from a folder, a wheel or a git commit, checks it, records the sha256 of its files, and keeps its settings, secrets and granted capabilities.
The contract is contracts/plugin-v1.
Once enabled, the plugin host runs it as one process and wires in what it contributes while it runs (running plugins).
Write one¶
The smallest plugin is examples/hello-tool: one MCP tool that greets a name.
hello-tool/
plugin.json the manifest
server.py an MCP server over stdio, the standard library only
{
"plugin_api": "1.0",
"name": "hello-tool",
"version": "0.1.0",
"tandemapp": ">=0.15",
"hooks_api": "1.0",
"entry": {"command": ["python3", "server.py"]},
"contributes": {
"tools": [{
"name": "greet",
"description": "Say hello to someone by name.",
"inputSchema": {"type": "object", "properties": {"name": {"type": "string"}},
"required": ["name"], "additionalProperties": false},
"annotations": {"readOnlyHint": true, "destructiveHint": false,
"idempotentHint": true, "openWorldHint": false}
}]
},
"settings": {"type": "object", "additionalProperties": false,
"properties": {"greeting": {"type": "string", "default": "Hello"}}}
}
In Python, the plugin SDK writes this reader for you: a plugin is a few decorated functions, and tandemapp-plugin new starts one.
Check it the way an install does, without installing it:
python tools/plugin_check.py path/to/hello-tool
ok hello-tool 0.1.0 sha256 7c51... (2 files)
Two more examples: audit-hook (an observer hook at request.finished) and classify-provider (a decision provider for classify, with a secret and a network host).
The manifest¶
Every field not listed here is refused, not ignored.
| field | what |
|---|---|
plugin_api |
the plugin-v1 version the manifest is written for, 1.0 |
name |
the plugin's id: lowercase letters, digits and dashes, at most 48. One plugin of a name. |
version |
MAJOR.MINOR.PATCH, with an optional -pre |
kind |
plugin (default): a program the plugin host runs. engine-stats: a package an engine loads to send its figures; recorded only. |
title, description, author, license, homepage |
for the page |
tandemapp |
the TandemApp versions it runs on, e.g. >=0.15, <0.17 (>=, >, <=, <, ==, !=, ~=, ==0.16.*) |
hooks_api |
the hooks-v1 version it speaks (kind plugin) |
entry |
{command: [argv...], env?: {NAME: value}}: started from the manifest's folder, never through a shell (kind plugin) |
trust |
sandboxed (default), host or engine: where it asks to run |
contributes |
hooks, tools, decision_providers, backends, panels, skills, engine_hooks (below) |
settings |
a JSON schema of type object: the plugin's settings, drawn as a form |
secrets |
[{name, description?}], names like API_KEY |
capabilities |
what it asks for (below) |
engine_stats |
kind engine-stats: {engine, package, entry_points, install?, env?} |
git |
{submodules: "ignore"}, {lfs: "ignore"}: see git sources |
Contributions¶
| key | each item |
|---|---|
tools |
an MCP tool: name, description, inputSchema, annotations, optional title and outputSchema |
hooks |
name, stages (hooks-v1 stages), role (transform, guard, decider, observer: one the stage takes), payload (meta by default) |
decision_providers |
name, questions (the conductor's: classify, packages, deliverable, memory_intent, memory_gate, judge) |
backends |
name, description, models |
panels |
name, title, path: an HTML file in the plugin, shown in a sandboxed frame |
skills |
folders in the plugin, each holding <skill>/SKILL.md; each becomes one more skill folder |
engine_hooks |
name, wheel (a .whl in the plugin), hooks (the engine extension's: plan, prompt, at_request, at_block, at_tool_call, check_answer, at_finish, extras, follow_ups, finish); needs trust: engine |
Tools: the four annotations and strict input¶
Every tool states all four MCP annotations as booleans: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. Its inputSchema is of type object and says "additionalProperties": false on every object in it, nested ones and array items included. A tool that misses one annotation, or a schema that allows extra properties (missing, true, a schema, patternProperties), is refused at install, naming the tool and the annotation or the place in the schema.
Settings¶
The settings schema is drawn as a form (one generator for plugins, hooks and the conductor's documents: proxy/schemaform.py, and dashboard/src/lib/schema-form.ts for the page). To keep the form and the checks honest it must:
- be of type object, and say
"additionalProperties": falseon every object; - use only the keywords a form reads:
type,properties,required,items,enum,const,anyOf/oneOf(a nullable value, or a list of constants), local$refto$defs,title,description,default,examples,readOnly,format,pattern,minLength,maxLength,minimum,maximum,exclusiveMinimum,exclusiveMaximum,multipleOf,minItems,maxItems,uniqueItems,minProperties,maxProperties; - have defaults that hold against their own schema;
- nest at most 4 levels and hold at most 200 fields;
- hold no secret: a secret is a name in
secrets, sealed apart and never shown again.
Capabilities¶
A plugin gets nothing by default. It asks in capabilities; the admin grants each one in the settings interface. Granted is always a part of what was asked.
| capability | means | grant |
|---|---|---|
prompts:meta |
a hook or provider sees ids, model, sizes, counts, timings, class and tool names | pairing's rights |
prompts:redacted |
as meta, plus the content after the conductor's redaction | pairing's rights |
prompts:full |
prompts and answers as they are | pairing's rights and a second confirm |
network:<host>[:<port>] |
it may connect to this host (a DNS name or an IPv4 address) | pairing's rights; a second confirm outside the LAN |
settings:read |
it may read the settings interface's values (never a secret) | pairing's rights |
engine:control |
it may restart the engine or change its mode through the controller | pairing's rights and a second confirm |
secrets:<NAME> |
the declared secret NAME is passed to its process | pairing's rights |
A contributed hook's payload needs a prompts: capability at that level or above; a decision provider needs one. Whatever it asks for, a plugin never reads the config database, another plugin's secrets, pairing keys or backend keys.
The plugin host checks each capability where it is used, and a refusal is journaled: in the plugin's status (refusals) and in the audit table (refused, by plugin:<id>, the capability's name, never a value).
| capability | checked where |
|---|---|
prompts:<level> |
a hook's payload when it is registered and at each call; a decision provider's input |
network:<host>[:<port>] |
the sandbox's egress filter: only these hosts |
settings:read |
tandem/settings and the panel bridge's settings.read |
secrets:<NAME> |
the process's environment and tandem/secret |
engine:control |
refused, whatever is granted, until engine control for plugins exists |
Install¶
POST /v1/fleet/plugins {"source": {"type": "folder", "path": "/srv/plugins/hello-tool"}}
POST /v1/fleet/plugins {"source": {"type": "wheel", "path": "/srv/hello_tool-0.1.0-py3-none-any.whl"}}
POST /v1/fleet/plugins {"source": {"type": "git", "url": "https://example.com/hello.git",
"commit": "<40 hex digits>", "subdir": "plugins/hello"}}
POST /v1/fleet/plugins/inspect with the same source runs every check and installs nothing.
A wheel that is not on the controller's disk can be sent to it: POST /v1/fleet/plugins/upload?name=hello_tool-0.1.0-py3-none-any.whl with the wheel's bytes as the body (Content-Type: application/octet-stream, at most 32 MiB, pairing's rights). The controller keeps it in its plugins' upload folder for an hour and answers the source to inspect and install it with; after that it is removed.
GET /v1/fleet/plugins carries each plugin's run state from the plugin host (run: its state, restarts, last error and gave_up), so a list needs no status call per plugin. Every plugin's view names the requested capabilities whose grant takes the second confirm (capabilities.confirm), as inspect does. Every time in the API is in milliseconds since the epoch.
Nothing in a plugin runs at install. A folder is copied file by file. A wheel is read as a zip, never through pip: its manifest is at its root or in one top-level folder, every member stays inside the tree, no member is a symlink, and the hashes in its RECORD must hold. A git source is fetched into an empty repository with no system or user git config, no hooks and no prompt, over https, ssh or file only, and its files are read out of the commit one blob at a time: no checkout, so no filter, attribute or LFS smudge runs.
A git source is pinned to a commit: the full id (40 hex digits). A branch name, a tag name or a short id is refused, because each can move. A submodule or an LFS file refuses the install, since its content is not in the commit, unless the manifest says "git": {"submodules": "ignore"} or {"lfs": "ignore"}: then the submodule's folder stays empty and an LFS file stays a pointer.
The checks, each a refusal with its code and the manifest field it is about (contracts/plugin-v1/api.json checks lists them all):
- the manifest parses, fits the schema and its kind's rules;
- the tools' annotations and strict input schemas;
- unique names within each contribution; hooks at real stages with a role the stage takes; providers for real questions;
- paths that stay in the plugin and exist;
secrets:<NAME>names a declared secret; payloads covered by aprompts:capability;engine_hooksonly withtrust: engine;- the settings schema, as above;
tandemappholds for this TandemApp,hooks_apiandplugin_apiare not newer than this controller's (same major, minor not newer). A refusal names the needed version and this one's;- a signature, when there is one, holds;
- with the policy on, a sandboxed plugin carries a trusted signature (409
signature_required).
The tree's sha256 and a signature¶
The install records the sha256 of the plugin's files: sha256 over plugin-tree-v1\n and a line a file, in byte order of the path, <sha256 of the file> <x or -> <path>\n (x: executable). .git and __pycache__ folders, .pyc, .DS_Store and ._* files are not part of the tree; a symlink or a special file refuses it. The registry checks the tree again when the plugin is enabled and before it is started, and plugin.sig.json with it (the tree's sha256 leaves the signature out, so the registry records the signature file's own sha256): a tree or a signature that changed reads mismatch (or missing), with the reason, and does not load until it is installed again. The health page names it (plugin_tampered).
A plugin may carry a signature, plugin.sig.json at its root (signing). When it is present it must hold, or the install is refused (signature_invalid).
Lifecycle¶
| install | the plugin is stored under the controller's state dir, plugins/<name>/<version>/, disabled |
| enable | checks the tree and the compatibility with this TandemApp first |
| disable | always works |
| upgrade | install the new version with "upgrade": true. Settings whose property is still there and whose value still holds, secrets still declared and capabilities still asked for are kept; the rest is dropped and listed. A new capability starts ungranted (listed in new): it takes its own grant. The old version's folder is removed. The same version with other files is refused (raise the version); an older version needs "allow_downgrade": true, signed or not. A version that asks a higher trust level, or whose host grant rested on a signature it no longer carries, is refused (409 trust_confirm_needed) and the installed version keeps running, until it comes again with "confirm_trust": "<plugin id>" (trust). |
| remove | refused while a hook names the plugin (409 referenced, with the hooks); takes its folder and secrets |
An install cut short leaves nothing: the files move into place before the registry row is written, and the next start removes a staging folder or a version folder no row names.
Sign a plugin¶
tools/plugin_sign.py makes an ed25519 key and signs a plugin folder with it; it never prints the private key.
python tools/plugin_sign.py keygen ~/keys/acme-plugins.pem # 0600, never overwritten
public_key g2KYlmjw...UZJzY=
fingerprint sha256:27b251a6f466ff65ffa8c9f9dc4a3033d3752871cc05faea0637f08152a37788
python tools/plugin_sign.py sign --key ~/keys/acme-plugins.pem path/to/hello-tool
python tools/plugin_sign.py verify path/to/hello-tool --fingerprint sha256:27b2...7788
--passphrase-env NAME encrypts the key at keygen and reads the passphrase at sign. Publish the public key and its fingerprint where your users can compare them. Sign last: a file changed after signing breaks the signature.
What is signed. plugin.sig.json holds {format, algorithm, public_key, plugin, version, tree_sha256, manifest_sha256, signature}: format is tandemapp-plugin-sig-1, algorithm ed25519, public_key the base64 of the key's 32 bytes, tree_sha256 the tree's sha256 (above: it folds in every file's sha256) and manifest_sha256 the sha256 of plugin.json's bytes. signature is the base64 of the 64-byte ed25519 signature over five lines of UTF-8, each ending in \n:
tandemapp-plugin-sig-1
plugin <name>
version <version>
tree <tree_sha256>
manifest <manifest_sha256>
The install checks each part: the tree, the manifest, the name and the version must be this plugin's, and the signature must hold. A key's id is the first 16 hex digits of its fingerprint, the sha256 of its 32 bytes.
Trust¶
A signature that holds is only trusted when its key is one this TandemApp trusts for that plugin at that level. A signature by any other key counts as none.
A route that takes pairing's rights (install, upload, enable, remove, a trust grant, the keys and the policy) answers 403 trust_required to a caller that may change the configuration but has not those rights (with no admin password set: any other machine), and 401 to one that may not change the configuration at all.
Trusted keys (/v1/fleet/plugin-trust, pairing's rights to change). Adding a key takes its fingerprint typed or pasted back: compare it with the one its publisher published. Without it the answer is 428 fingerprint_confirm_required with the fingerprint to compare; a different one is 422 fingerprint_mismatch. A key can be limited to plugin ids (plugins) and to trust levels (levels); null means any. Removing a key takes its fingerprint as well. To change a key's limits, remove it and add it again.
POST /v1/fleet/plugin-trust/keys {"public_key": "g2KYlmjw...UZJzY=", "name": "Acme plugins",
"plugins": ["hello-tool"], "levels": ["sandboxed", "host"],
"confirm_fingerprint": "sha256:27b251a6...7788"}
DELETE /v1/fleet/plugin-trust/keys/27b251a6f466ff65 {"confirm_fingerprint": "sha256:27b2...7788"}
POST /v1/fleet/plugin-trust/policy {"require_signature_sandboxed": true}
The levels.
| level | runs when | a grant takes |
|---|---|---|
sandboxed |
always; with require_signature_sandboxed on (off by default), only with a trusted signature, refused at install, enable and load otherwise |
nothing |
host |
it holds a host grant | pairing's rights, and either a signature trusted for host (basis signature) or the plugin's id typed (basis typed). A grant on a signature holds only while that signature stays trusted: remove the key, and the plugin stops until it is granted again |
engine |
not yet: the in-process chain does not exist | per engine host: a signature trusted for engine AND the plugin's id typed. The grant is recorded; the plugin is refused at runtime until engine extensions install through ext install |
GET /v1/fleet/plugins/<id>/trust what it asks, what it has, its signature,
whether it runs and what a grant takes
POST /v1/fleet/plugins/<id>/trust {"level": "host", "confirm": "<id>"}
POST /v1/fleet/plugins/<id>/trust {"level": "engine", "engine": "<engine host>", "confirm": "<id>"}
POST /v1/fleet/plugins/<id>/trust {"level": "sandboxed"} revoke every grant
POST /v1/fleet/plugins/<id>/trust {"level": "sandboxed", "engine": "<host>"} revoke one engine
A grant without the typed confirmation where one is needed is 428 typed_confirm_required; a wrong one is 422 typed_confirm_mismatch; an engine grant without a trusted signature is 409 signature_required. The settings interface's trust key grants host only for a plugin signed by a key trusted for host (with its second confirm); for an unsigned one it answers 409 and points here.
Updates. A new capability starts ungranted. A version that asks a higher level than the installed one, or whose host grant rested on a signature this version does not carry, waits for confirm_trust (the plugin's id): the installed version keeps running meanwhile. With it, the upgrade goes ahead, and a host plugin's grant is renewed on the new version's trusted signature or, unsigned, on the typed confirmation. A host grant carries over an upgrade that still asks host; an engine grant carries over while the new version is still signed by a key trusted for engine. Going back to an older version, signed or not, takes allow_downgrade.
Audit. Each trust decision is a row of the audit table: a key trusted or distrusted (with its fingerprint), the policy set, a grant or revoke (its level, basis, key and engine host), and each refusal at install, upgrade, enable, load or grant (refused, with where and why). The health page names a plugin that may not run as it asks (plugin_untrusted) or that changed (plugin_tampered).
Running plugins¶
The plugin host in the controller starts one process for each enabled plugin of kind plugin, from entry.command (argv, never a shell) in the manifest's folder. It reads the registry every 2 seconds and at each change: a disabled or removed plugin stops, a plugin whose settings, secrets, grants or version changed starts again with them.
Trust levels¶
trust |
where it runs | how |
|---|---|---|
sandboxed (default) |
a container (Docker or Podman) or a Kubernetes pod of the chat sandbox's class | always, signed or not, unless the policy requires a trusted signature for sandboxed plugins; it waits when there is no sandbox runtime here |
host |
a process of the app's user, outside any sandbox | only once granted (trust): on a signature by a trusted key, or with the plugin's id typed; until then it does not start |
engine |
a wheel inside the engine | a grant per engine host takes a trusted signature and the plugin's id typed; refused at runtime until the in-process chain exists |
The sandbox. The sandbox image (QSE_SANDBOX_IMAGE, tandem-sandbox:1), uid 1000, every capability dropped, no-new-privileges, a read-only root, a small in-memory /tmp, no devices, 512 MiB (TANDEM_PLUGIN_MEM_MB), one CPU and 128 processes, and no network but its loopback. Mounted: the plugin's installed tree at /plugin, read-only; its own folder at /workspace (TANDEM_PLUGIN_DATA) and a home at /home/agent. Nothing else of the controller's: not the config database, not another plugin's folder or secrets. Its way out is the chat sandbox's egress proxy (HTTP_PROXY and HTTPS_PROXY are set) with a host list: only the hosts of its granted network: capabilities, a granted LAN address included; any other address is refused, and this box (loopback), link-local addresses and the Kubernetes API are refused even when granted.
Which runtime. The one chatd uses on this install: QSE_SANDBOX_BACKEND, QSE_SANDBOX_SOCKET and QSE_SANDBOX_IMAGE from the controller's environment or chatd's env file (<state dir>/chatd.env). TANDEM_PLUGIN_SANDBOX (auto, docker, kubernetes, off) overrides it. In a cluster a plugin's pod is made like a chat's sandbox pod, its tree a read-only subPath of the release's volume, and reaches only the plugin host's egress port (sandbox.kubernetes.pluginEgressPort, 3129, TANDEM_PLUGIN_EGRESS_PORT). With no runtime a sandboxed plugin does not start: its state is unavailable and the health page says why (plugin_no_sandbox).
The environment holds only what the grants allow, never the controller's:
| variable | what |
|---|---|
TANDEM_PLUGIN, TANDEM_PLUGIN_VERSION |
its id and version |
TANDEM_PLUGIN_SETTINGS |
its own settings as JSON, each schema default filled in |
TANDEM_PLUGIN_DATA |
its own data folder |
TANDEM_PLUGIN_CAPABILITIES |
the capabilities granted, a JSON list |
<NAME> |
each secret granted by secrets:<NAME> (a name the process itself uses, such as PATH or HOME, is not passed) |
entry.env, LANG, PYTHONUNBUFFERED |
the manifest's own values and two defaults |
A host plugin also gets this process's PATH, and its data folder as HOME.
Supervision¶
A plugin that exits, or does not answer initialize within 20 seconds, is started again after 1, 2, 4, 8, 16, 32, then 60 seconds. At the fifth failure within an hour the host gives up: it disables the plugin (audited, by plugin-host) and the health page names it (plugin_failed) until it is enabled again. A stop by hand holds it until a start by hand. Removing a running plugin ends its process before its folder goes.
The protocol¶
MCP over stdio, one JSON-RPC 2.0 message a line, protocol revision 2025-06-18: initialize, then tools/list when the manifest declares tools, tools/call, ping. Three more methods carry what MCP has no words for, and the plugin answers those it contributes:
| method | params | answer |
|---|---|---|
hooks/call |
the hooks-v1 envelope (hooks, id, stage, ts, payload, mode, request, event) with hook set to the contributed hook's name and hook_id to the runner's id |
a hooks-v1 result: {action: continue\|modify\|deny\|decide, patch?, decision?, reason?, labels?} |
decision/ask |
{provider, question, instructions, options, model, deadline_ms, payload, input}; input is {chars} at meta, {text} at redacted (after the conductor's redaction) and full |
{label, confidence?, probabilities?}: label one of options |
backend/request |
{backend, method, path, body} |
{status, body}, or {status, events: [...]} for a stream (each event one SSE data: line) |
The plugin may ask the host, with requests of its own on the same stream:
| method | params | needs |
|---|---|---|
tandem/settings |
none | settings:read: its own settings |
tandem/secret |
{name} |
secrets:<name>; another plugin's secret never |
tandem/engine |
any | refused until engine control for plugins exists |
A refusal is the JSON-RPC error -32001 with data.capability. The calls are local, so they carry no signature; the payload levels still apply.
Contributions¶
Each contribution is registered while the plugin runs and is gone when it stops. A plugin's status says what was registered and what was not, and why (notes).
Tools¶
Offered to the Chat tab: chatd lists them with its MCP servers (plugin:<id>, transport plugin, read-only there) as mcp__plugin_<id>__<tool>, and calls them through the controller (/chat-engine/v1/plugins/tools, /chat-engine/v1/plugins/tools/call), so Chat must be on to use them. Only a tool the manifest declares and the server lists is offered, with the manifest's checked schema and annotations; arguments outside the schema are refused before the plugin sees them.
Hooks¶
Each hook joins the runner as <plugin>/<hook>: priority 100, mode on, no scope, the manifest's stages, role and payload. A hook whose payload is above the plugin's granted prompts: level is not registered. To set its priority, scope, mode or policy, add a hook of kind plugin on the hooks' API with target <plugin>/<hook> (at the declared stages, role and payload or below): it takes the contributed hook's place. The runner's timeouts, breaker and policies apply as for any hook.
Decision providers¶
Each provider is registered as <plugin>/<provider> in shadow: asked off the request's path and journaled, never used. To have it answer, add a decision provider of kind plugin with target <plugin>/<provider> and the mode you want (on, ab): it takes the contributed one's place.
Backends¶
Each backend becomes a row of the backends store, plugin-<id>-<name> (kind generic, the manifest's models, labelled "(plugin /plugin-backends/<id>/<name>: requests that the gateway routes there go to the plugin as backend/request, GET /v1/models answers the manifest's models. That route answers this machine only. The row is removed when the plugin stops.
Skills¶
Each skill folder of a running plugin is one more skill folder of the controller's conductor, after the packages document's own skill_dirs, read from the installed tree (never written).
Panels¶
A panel is served at /plugin-panels/<id>/<panel>/ (its HTML; the files beside it under the same path) with Content-Security-Policy: sandbox allow-scripts allow-forms; default-src 'none'; ...; connect-src 'none': in the page's iframe or on its own it has an opaque origin, so it reads no cookie, storage or route of the controller's. It talks to the page with postMessage({type: 'tandem-bridge', id, method, params}); the page relays the call to POST /v1/fleet/plugins/<id>/bridge and posts back {type: 'tandem-bridge-result', id, result | error}.
| bridge method | needs |
|---|---|
plugin.info, plugin.status |
nothing |
tools.call {tool, arguments} |
the tool is the plugin's own and read-only (readOnlyHint) |
settings.read |
settings:read |
engine.control |
refused: not available yet |
GET /v1/fleet/plugins/<id>/panels lists them with the bridge's methods this plugin may use.
Write a sandboxed plugin¶
- Use the standard library, or vendor what you need into the plugin: the sandbox has the image's Python 3.12 and Node, its root is read-only, and its network reaches only the hosts you ask for.
- Read your settings from
TANDEM_PLUGIN_SETTINGS; keep files inTANDEM_PLUGIN_DATA. - Ask for
network:<host>[:<port>]for each host you call; HTTP clients that honourHTTPS_PROXY(urllib, requests, curl) go through the proxy as they are. - Write logs to stderr; stdout is the protocol.
examples/hello-tool,audit-hookandclassify-providerare complete plugins written against the protocol itself;note-webhookandkeyword-routerare built on the SDK. The tests run each of them.
Debugging¶
| what | where |
|---|---|
| running or why not, restarts, the last error, what was registered, the refusals | GET /v1/fleet/plugins/<id>/status |
its stderr and the host's lines about it, every secret value replaced by [secret NAME] |
GET /v1/fleet/plugins/<id>/logs?tail=200; <state dir>/logs/plugins/<id>.log (1 MiB, then one older file) |
| start again, stop (held), start | POST /v1/fleet/plugins/<id>/restart, /stop, /start |
| a hook's calls and breaker | GET /v1/fleet/hooks/<id>/calls for a hook of kind plugin; the runner's metrics for <plugin>/<hook> |
| a plugin that gave up, has no sandbox, changed since its install or is not trusted as it asks | the health page's controller findings |
| why it may not run at its level | GET /v1/fleet/plugins/<id>/trust |
The API¶
| route | rights |
|---|---|
GET /v1/fleet/plugins |
the configuration's |
POST /v1/fleet/plugins/inspect {source} |
the configuration's |
POST /v1/fleet/plugins {source, upgrade?, allow_downgrade?, confirm_trust?} |
pairing's |
POST /v1/fleet/plugins/upload?name=<file>.whl (the wheel's bytes) |
pairing's |
GET /v1/fleet/plugins/{id} |
the configuration's |
GET /v1/fleet/plugins/{id}/trust |
the configuration's |
POST /v1/fleet/plugins/{id}/trust {level, engine?, confirm?} |
pairing's |
GET /v1/fleet/plugin-trust |
the configuration's |
POST /v1/fleet/plugin-trust/keys, DELETE /v1/fleet/plugin-trust/keys/{key}, POST /v1/fleet/plugin-trust/policy |
pairing's |
POST /v1/fleet/plugins/{id}/enable |
pairing's |
POST /v1/fleet/plugins/{id}/disable, /verify |
the configuration's |
DELETE /v1/fleet/plugins/{id} |
pairing's |
GET /v1/fleet/plugins/{id}/status, /logs, /panels |
the configuration's |
POST /v1/fleet/plugins/{id}/start, /stop, /restart, /bridge |
the configuration's |
Pairing's rights are the admin's, or this machine's while no admin password is set. No answer holds a secret. Starting a plugin takes it enabled first, which takes pairing's rights.
Settings, secrets and capabilities¶
They are the settings interface's plugins scope, one target a plugin: GET /v1/settings/plugins/schema?target=<id>, then plan and apply as for any scope (settings). Its keys are enabled, settings.<property>, secrets.<NAME> (write-only), capabilities.<capability> and, for a manifest that asks trust: host, trust (host only on a trusted signature; trust). Each plugin keeps its own versions.
The Plugins pages¶
The dashboard has all of this under Settings, Plugins.
- The list. Each installed plugin with its version, its kind, where it came from, its trust level, its signature and its state. The state is the run state the list carries; no plugin is asked alone.
- Install. A folder or a wheel on the controller's machine, a wheel uploaded from this computer, or a git URL with a full commit id. The source is checked first. The page then shows every check with how it ended, the sha256 of the files, where the plugin asks to run, each capability in plain words with its risk, and what it adds. Install comes after that. A refused source installs nothing; each reason stands with what to change and the controller's own sentence.
- A plugin's page. Its state, restarts and last error, with start, stop and restart; what it adds and where each shows; its settings as a form drawn from its schema; its secrets, set or removed and never shown; each capability with its grant; its log; its files, with a check against the sha256 of the install; a newer version; and its removal. A plugin that is off has one button that stages the switch and everything it asks for.
- A panel. The plugin's own page in a sandboxed frame. The page relays the frame's bridge calls to
/v1/fleet/plugins/<id>/bridge, only the methodsGET .../panelslists for it; anything else is refused on the page. A panel that cannot be shown says why.
The switch, the settings, the secrets, the grants and the trust level are staged and go through the settings' review, which asks a second time for prompts:full, engine:control, a network host outside the LAN and the host. Install, upgrade, removal, start, stop and restart are done at once.
A wheel is named by its path on the controller's machine, or uploaded from the browser's computer through POST /v1/fleet/plugins/upload: the page then checks it from the path the controller answers, which holds for an hour. Which grants ask a second time is the controller's word (capabilities.confirm); the page reads a host itself only for a controller that does not say.
The engine-stats plugins¶
The two packages in plugins/ that an engine loads to send its figures have a manifest of kind engine-stats. The controller can check and record them; installing them into the engine stays pip install plugins/<engine>.