Distribute, install, and use a plugin

A finished plugin is distributed as dist/plugin.raydo.zip. The SDK and scaffolder live on npm; the plugin archive itself does not need to be an npm package.

Distribution options

Developers can share the archive through:

a GitHub Release;
a product or company download page;
an internal artifact repository;
a direct file transfer for a controlled preview.

Always distribute the archive with its expected publisher, version, manifestDigest, and packageDigest. Use HTTPS or an authenticated internal channel. Do not distribute source directories as if they were reviewed archives.

Community publishing activation

Raydo Hub now has the bounded Community plugin contract, but public self-service submission remains disabled until the publishing terms, abuse and security contacts, legal review, and operational block tooling are activated together. A Community listing is publisher-attested; it is not a Raydo safety or quality certification.

Publish through Raydo Hub Community Plugins

The Community flow separates public discovery from package custody:

Host the exact plugin.raydo.zip archive on publisher-controlled HTTPS infrastructure. Raydo Hub does not upload, proxy, or store the archive bytes.

Enroll an Ed25519 publisher key in Hub. Keep the private key outside Hub and rotate or revoke it if it may be compromised. Hub returns the exact publisher ID for the account.

Replace the scaffold's developer publisher placeholder with that exact Hub publisher ID before npm run verify and npm run pack. The package manifest, install envelope, signed descriptor, and authenticated Hub account must all name the same publisher.

Create the closed raydo.hub.plugin-release-descriptor.v1 descriptor. Bind the publisher and key, plugin ID and version, immutable archive URL, byte size, manifestDigest, packageDigest, compatibility, capabilities, connectors, permissions, and effects.

Sign the canonical descriptor and submit only the descriptor. Hub verifies publisher namespace ownership, the active key, signature, immutable identity, public URL rules, bounded projection, and moderation readiness.

Hub lists an accepted release as Community · Publisher-attested and Hosted by publisher. Reports, withdrawal, blocking, and publisher suspension can remove it from public discovery without taking custody of the package.

A user selects Review and install in Raydo Desktop. Desktop authenticates the exact Hub descriptor endpoint, verifies the signature and descriptor digest, downloads directly from the publisher without redirects, verifies byte size plus package and manifest digests, and installs the package disabled in needs-review.

Listing never reviews, grants, connects, enables, or executes a plugin automatically. Browser mode remains read-only. Until the public submission feature is activated, publishers can prepare the same descriptor and continue distributing the exact archive through the direct channels above.

Install in Raydo Desktop

Browser mode is read-only. Installation, review, connection configuration, grants, and enablement require Raydo Desktop.

Download the exact plugin.raydo.zip archive from a trusted source.

Open Plugins / Plugin Center in Raydo Desktop and choose the local-file installation action.

Select the archive. Raydo validates its structure, manifest, schemas, permissions, portability, private-material boundary, and digests.

Confirm that installation ends in needs-review. The plugin cannot contribute or execute capabilities in this state.

Review the publisher, permissions, effects, connector requirements, capability schemas, manifestDigest, and packageDigest.

Approve the reviewed package. Approval moves it to a disabled state; it does not configure a connection or enable execution.

Configure authority and enable

For a connection-backed plugin:

Open App Connections and configure the required provider account or service.

Select the exact resource the plugin may use, such as a workspace, database, folder, or conversation.

Grant the reviewed capability only for the required resource and effect.

Return to Plugins and enable the reviewed package.

A purely local plugin may not require App Connections, but it still requires installation, review, and enablement.

Lifecycle states

State	Meaning	Can execute?
`needs-review`	Archive validation passed, but no human review authority exists.	No
disabled after review	Publisher, permissions, effects, and digests were reviewed; the plugin is intentionally inactive.	No
enabled and ready	Review is current and any required connection, resource, and grant are live.	Yes
enabled but not ready	The package is enabled, but a connection, resource, grant, or exact route is missing or stale.	No
frozen update	Installed bytes changed and the new identity has not been reviewed.	No

How users consume a plugin

An enabled plugin contributes Raydo capabilities instead of creating a separate application runtime. Depending on its declared surfaces, users can:

discover it in the Capability Library;
assign the capability to an Organization Role;
add the exact projection to a Workflow;
invoke it from a supported Chat or task path;
inspect normalized results, provenance, artifacts, and delivery outcomes in Raydo.

Execution still passes through Raydo's route, approval, connection grant, execution ledger, redaction, audit, artifact, and delivery owners.

Revocation and updates

Revoking a grant or connection removes readiness before a new external effect.
Disabling or uninstalling removes contribution eligibility.
Changing the manifest or package invalidates previous review authority.
A changed archive must be installed and reviewed as a new exact identity.
A plugin must never silently switch a saved Workflow to a different version, digest, route, or resource.

Troubleshooting checklist

Symptom	Check
Installation is rejected	Confirm the file is the original `.raydo.zip`, then compare both expected digests.
Plugin remains in `needs-review`	Complete review in Raydo Desktop; install alone never grants authority.
Plugin is enabled but unavailable	Check App Connections, selected resource, grant scope, and route readiness.
A Workflow says the plugin projection is stale	Re-open the Workflow and deliberately select the newly reviewed projection.
A write is blocked	Confirm the capability declares a write effect and that approval and idempotency requirements are satisfied.

Return to Develop and package a Raydo plugin when a new archive is required.

Distribute, install, and use a plugin

On this page