Skip to main content
Uploading a plugin adds a version to a capability. Versions are integers the platform assigns; exactly one is active at a time, and every agent and gateway bound to the plugin calls that one.

​
Uploading

​
Portal

Plugins → New plugin creates the capability and its first version. Plugins → your plugin → Versions → Upload version adds a version to an existing one. Either way you choose between two modes:
  • WASM component — a .wasm file, with an optional .wit file for tool descriptions.
  • .npack archive — the packaged output of noorle plugin build, carrying the component, noorle.yaml, the WIT file, and any .env defaults.
Limits: An upload larger than the accepted size is rejected before anything is stored. Plugin components are typically well under it; if you are close enough to wonder, see Size.

​
Management API

POST /v1/capabilities/upload accepts a .npack archive. A request whose body exceeds the accepted size is rejected with 413.

​
What happens on upload

  1. The archive is unpacked and the component is validated — Component Model binary, imports inside the nine allowed WASI prefixes, at least one exported function. Failure returns the errors and writes nothing.
  2. The component bytes are stored content-addressed by SHA-256.
  3. A dormant version row is appended, and the per-version metadata (noorle.yaml, environment defaults, WIT) is stored alongside it.
  4. One transaction records the integrity digests and flips the new version to active.
Because step 4 is a single commit, a successful upload is immediately live — there is no separate activation step for a normal upload. If step 4 fails, the version stays dormant and the previously active version keeps serving. A dormant version shows in the Portal with a No artifact badge and cannot be activated: it carries no activatable hash. Re-upload it.

​
Versions in the Portal

Plugins → your plugin → Versions lists every version, newest first. Each card shows:
  • the version number, an Active badge where applicable, and a Builder badge on versions produced by Plugin Builder;
  • the tools it exports, with their descriptions;
  • a read-only summary of its policy — allowed network hosts, storage permissions, environment variable keys, timeout and memory limits;
  • Edit configuration, which opens the per-version policy and credential drawer;
  • Set as active on any non-active version that has an artifact.

​
Rolling back

Open Versions and choose Set as active on the version you want. The switch is account-wide and immediate: there is one active version per plugin, and every agent, gateway, and workflow bound to it picks up the change. There is no per-binding version pin — agent_capability carries no version column — so you cannot run version 3 for one agent and version 2 for another. To stage a change, upload to a separate plugin and bind that one to a test agent.

​
Configuration changes without a rebuild

Policy is per-version data, not baked into the component. Use Edit configuration on a version to change allowed hosts, environment keys and values, timeout, and memory. See the noorle.yaml reference.
Credential values are shared across every version of the plugin, not held per version. Changing one from any version changes it for all of them.

​
Deleting

Deleting a plugin in the Portal removes the capability and all of its versions, permanently. Bindings to agents and gateways go with it.

​
Before you upload

  • The component builds and its tools carry doc comments in the WIT file — those become the descriptions a model reads.
  • noorle.yaml names only the hosts you actually call, with path_prefix and methods where the API allows it.
  • Secrets are declared as credentials, not hardcoded and not shipped in .env.
  • The timeout you request is realistic; the default is 30 seconds and the ceiling is 120.
  • You have somewhere to roll back to, or you accept that this upload goes live for every binding the moment it succeeds.

​
Next