Skip to main content

Plugin builder

The Plugin builder screen lets you write a Plugin manifest (capabilities, sandbox, permissions, signed OCI artefact), check it against the plugin-manifest contract and register it: the registry verifies the signature. Portal path: /studio/plugins. It is used by developers and tenant administrators who publish plugins; the pack itself is scaffolded and signed by the CI of the pack.

What the screen shows​

  • On the left, the list of the plugins (GET /v1/plugins), paginated, with New on top. An empty list shows No plugin yet.
  • Editor tab: Manifest (JSON) checked live against the plugin-manifest JSON Schema, the editor problems, Invalid JSON: ..., the buttons Validate on the server and Create or Save as a new version, the validation result and the answer of the registry.
  • Test tab, once a saved plugin is open: Registry status with the Read the status button (verification, sandbox runtime and deployment).
  • The starter manifest new-plugin holds artifact (OCI reference, digest, media type), signature (digest, signer), capabilities (one tool), sandbox (gvisor, network deny_all, read only root file system, CPU, memory and timeout limits) and permissions.
  • Opening a plugin reads its manifest from GET /v1/plugins/{name}.

Actions​

Button or actionWhat it doesAPI callRoles
NewLoads the starter manifest new-plugin.NoneEveryone
Click a plugin in the listLoads its stored manifest.GET /v1/plugins/{name}Every signed in user
Validate on the serverValidates the manifest against plugin-manifest.POST /v1/contracts/{name}/validateEvery signed in user
CreateRegisters the plugin; the registry verifies the artefact signature.POST /v1/pluginstenant_admin, developer
Save as a new versionRegisters the manifest with the patch number of metadata.version raised by one.POST /v1/pluginstenant_admin, developer
Read the status (tab Test)Reads verification, sandbox runtime and deployment of the plugin.GET /v1/plugins/{name}/statusViewer relation on the plugin
Retry (error state)Reads the list or the schemas again.GET /v1/plugins or GET /v1/contracts/{name}Every signed in user

Roles​

The portal enables the save buttons for STUDIO_WRITERS (tenant_admin, developer). The Control Plane accepts tenant_admin, developer and application_owner on POST /v1/plugins (WRITE_ROLES, services/control-plane/src/eai/domains/plugins/routes.py) and records the caller as owner of the plugin. GET /v1/plugins/{name}/status needs the viewer relation on the plugin. Installing a plugin is not done here: it stays in the catalogue.

Typical tasks​

Register a plugin built by the CI​

  1. Start from the template. Click New. Expected result: the manifest new-plugin. If it fails: reload the page.
  2. Reference the artefact. The registry checks what the CI produced. Copy the OCI reference, the digest and the signature given by the CI of the pack into spec.artifact and spec.signature. Expected result: No problem found by the editor. If it fails: a digest is sha256: followed by 64 hexadecimal characters.
  3. Set the sandbox and the permissions. Keep the network closed unless the plugin needs it. Expected result: valid JSON. If it fails: fix the line named by the problem.
  4. Validate on the server. Click Validate on the server. Expected result: Valid against contracts/v1. If it fails: read the error list.
  5. Create. Click Create. Expected result: the toast Saved as version 0.1.0 and the answer with apply_status. If it fails: see Troubleshooting.

Check the registry status​

  1. Open the plugin. Click it in the list. Expected result: the Test tab appears. If it fails: register it first.
  2. Read the status. Open Test and click Read the status. Expected result: the JSON with the verification, the runtime and the deployment. If it fails: plugin_not_found means the plugin is not registered.

Troubleshooting​

SymptomCauseFix
Error invalid_signature (401)The signature does not match the artefact.Take the digest and signature produced by the CI again.
Error plugin_blocked (403)The plugin is blocked by the registry.Ask a security officer why it was blocked.
Error invalid_manifest (422)The manifest breaks the contract.Fix the fields listed in errors.
Error pack_requires_marketplace (422)The artefact is a pack, installed through the marketplace.Publish it in the Pack catalog instead.
Error plugin_not_found (404) on statusThe plugin is not registered.Register it first.