Plugins

Plugins extend the panel with new pages, server tabs, API routes, scheduled work, and sign-in providers. Manage them under Admin → Extensions. A plugin runs in the panel process with the access you grant it, so every install is a trust decision — see security.

Prerequisites

• admin.read to browse, admin.write to install, enable, or change anything.
• Outbound HTTPS from the backend to the marketplace index and the package host. Loopback and private addresses are refused unless the host is one of your configured index hosts or the panel sets PLUGIN_MARKETPLACE_ALLOW_LOCAL=true.
• For a vendor-licensed plugin, the license key from the vendor.

Install a plugin

1. Open Admin → Extensions → Marketplace.
2. Browse the configured sources. The status tabs filter to All, Install, Update, and Installed; expand a row for its author, source, checksum, package URL, homepage, and licensing block.
3. Select Install. A package is a .catpkg.zip — a ZIP whose root contains plugin.json.
4. Installed code is staged inert. It is not imported and none of its hooks run until you accept the safety disclaimer and enable it.

Installing over an existing copy upgrades it in place. The same flow over the API needs a pinned checksum:

curl -X POST https://panel.example.com/api/plugins/install \
  -H "Authorization: Bearer $CATALYST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://cdn.example.com/my-plugin-1.0.0.catpkg.zip","sha256":"<64 hex chars>"}'

sha256 is required: the panel validates the 64-hex digest before it makes any network request (CHECKSUM_REQUIRED), and aborts before extracting if the downloaded bytes do not match (CHECKSUM_MISMATCH). An index entry without a digest shows Not published and cannot be installed.

The marketplace merges the official index (unless PLUGIN_MARKETPLACE_DISABLE_OFFICIAL is set), comma-separated PLUGIN_MARKETPLACE_URLS, and sources added from the panel. Add, enable, or remove panel-added sources in the marketplace’s Marketplaces rail; the official and environment sources are read-only. When two sources list the same plugin name, the newest version wins.

Enable a plugin and accept the safety disclaimer

Nothing in a plugin executes before an accepted disclaimer — discovery only reads plugin.json.

1. In Admin → Extensions → Plugins, switch the plugin on.
2. The Enable dialog lists the author, version, every declared permission with its risk copy, and — for a licensed plugin — the activation endpoint it will contact. It warns that a plugin can contact external services, read the data permitted above, and keep running until you disable it.
3. Tick the acknowledgement and select Accept & Enable. The panel records who accepted, when, which version, and which permissions were in scope.

Consent is required again when the plugin’s version changes, when its declared permissions grow beyond the accepted set, or when the disclaimer version changes. Re-enabling an unchanged plugin does not ask again. An update that changes either is left disabled after the copy lands (reload included) until you accept the new disclaimer.

A plugin that was already enabled before this feature existed keeps starting: the panel records a backfill acceptance with no accepting user and flags the row Review access.

Disabling a plugin makes its routes answer 503 and clears its scheduled work and WebSocket handlers. Event listeners stay registered until the plugin is unloaded (reload or uninstall).

Grant and revoke plugin permissions

A plugin declares the capabilities it wants in plugin.json; you decide which it receives. Open the plugin’s Details → Permissions, toggle, save. Grants must be a subset of the declared list, and every change is audit-logged.

Revocation applies to the next call: data reads, file operations, and plugin-to-plugin calls fail immediately, with no restart. Mounted routes, scheduled work, and event listeners stay until you disable or unload the plugin.

Plugins can also expose permissions for panel roles (a separate namespace from the plugin’s own capabilities). While a plugin is enabled they appear in the role editor under Plugins — see roles.

Configure a plugin

Open the plugin’s Settings, fill in the fields its config schema declares, and save. The running plugin reads the new values immediately. The control type comes from each field’s type; see config field types. The panel validates nothing on save, so a plugin must check what it reads.

Update, reload, disable, uninstall

• Version column — the installed version, plus the marketplace version when it is newer (an Update 1.0.0 → 1.0.1 badge), or Up to date / Not in an index.
• Update — installs the newer listing over the running copy. The list header shows N updates available, which links to the marketplace filtered to pending updates, where Update all (N) applies them one at a time.
• Reload — re-reads the plugin from disk without restarting the panel, and leaves it disabled if the new copy needs consent.
• Disable — stops the plugin; its files and settings stay installed.
• Uninstall — removes the code and unloads it. Also delete stored data additionally removes config values, key-value storage, collections, and consent history, and cannot be undone.

Licensing

Catalyst does not issue or validate plugin licenses. A vendor plugin declares a licensing block in plugin.json; the panel discloses the phone-home before you enable it, hands the plugin a stable install ID, and refuses to install a package marked encrypted that ships no encrypted backend payload.

Put the vendor’s license key in the plugin’s config (usually licenseKey) and reload it. Activation is cached in the plugin’s own storage (7 days by default), so a vendor outage does not immediately take the plugin down; when activation fails the plugin degrades or fails according to its declared failMode. See plugin licensing.

Related

• Least-privilege roles and plugin-exposed permissions: roles & permissions.
• Trust boundaries and hardening: security.
• Building a plugin: plugin development.