Coming soon. The Wiki is in active development, so features and these docs may still change. Early adopters: contact us for access.

Plugins

Install signed plugins that check or react to actions, add blocks to pages, convert imported macros, keep their own data and bring their own screens

Plugins extend the Wiki with your own logic. A plugin is a signed package that runs in a sandbox and receives events: it can check an action before it happens (and block it or adjust allowed values), or react after it happened (for example send an alert). A plugin can also add blocks people insert into pages, convert macros when another wiki is imported, keep its own data, call web services you allow, take settings and bring its own screens.

License: Pro or higher. Permissions: plugins:read to see installed plugins; plugins:admin to install, approve, activate and remove them, change their settings and manage signing keys (super admins).

1. Installing a plugin

Settings → Plugins lists the installed plugins: each with its version, status (active, waiting for approval, inactive), what it brings (screens, events, permissions, secrets) and, for active plugins, whether its calls are working on this server. Plugins waiting for approval, and plugins that are failing or paused, are listed first with what to do: Review and activate, or Restart. Filter by status or search by name or description. The side column links to Trusted signing keys and Leftover data.

Settings → Plugins: plugins that need attention, the list by status, the upload area and the side column
Settings → Plugins: plugins that need attention, the list by status, the upload area and the side column
  1. If the plugin is signed by a key your server doesn't trust yet, go to Settings → Plugins → Trusted signing keys and add its public key (you get it from the plugin's author).
  2. Go to Settings → Plugins, choose Upload plugin and pick the .zip package, or drop the package on the upload area under the list.
  3. The plugin's page opens with Set up: a summary of what the plugin needs, then only what's missing (see Finishing setup). Review the events it receives, the permissions it asks for, the services it answers and, for data and network permissions, its limits and the web addresses it may call. Tick I approve these permissions and choose Activate.

Uploading a plugin that's already installed upgrades it. If the new version asks for permissions that weren't approved before, it waits for approval again; otherwise it stays active. Its data and settings are kept.

Changes to one plugin run one at a time. If someone else upgrades, activates, deactivates or uninstalls it while you do, your change is refused (plugin_changed): reload the page to see its current state, then try again.

Deactivate stops a plugin but keeps it installed, with its data; Uninstall removes it and its package (see Data, network and secrets for what happens to its data). Blocks it added to pages stay in the pages and show their text while the plugin isn't active.

2. Finishing setup

After you upload a plugin that isn't running yet, its page opens a setup guide. It starts with a summary of everything the plugin needs, each marked done, needed, optional or blocked, and a link to the plugin's documentation when it has one. Then it asks only for what's missing:

  • Secrets and required settings. A plugin can mark secrets and settings as required, and say where to get a value. It can't be activated until they are set: activating it is refused, and the guide opens at the missing fields. While it's active, a required secret can be replaced but not removed, and a required setting changed but not cleared.
  • Approval. The permissions it asks for, approved all at once, then Activate.
  • Things only your operator can fix are shown as blocked or as notes: the Wiki's database role can't create plugin databases, or plugin web requests are turned off on this server (PLUGIN_EGRESS=false).

Finish setup on the plugin's page (with a Setup incomplete mark while something required is missing) opens the guide again. An upgrade that adds a required secret or setting stops the plugin, keeping its approval, until the value is set and it is activated again.

3. Permissions

PermissionWhat it allows
events:interceptCheck actions before they happen, block them, or change the values the event allows
events:subscribeReceive events after they happen
alerts:createSend alerts to people
db:ownIts own database schema, which only it can reach
kv:ownIts own key-value store (counters, short-lived values)
net:outboundCall the web addresses listed in its package, and only those
services:provideAnswer requests a Wiki feature sends it, for the services listed under provides (see Services). The plugin's page says, for each service, what the requests carry
api:exploreFrom its screens: call the REST API as the person using them, through the Wiki, with that person's access. The Wiki sends each request itself, never sends routes that answer with a secret (such as creating a token) or sign-in routes, asks the person before every change, and records the plugin in the audit log (via: plugin:<name>)
mcp:serveOffer tools to AI applications at its own address, /mcp/<plugin name> (see OAuth applications)

A plugin can't be activated with only some of the permissions it asks for. Without these permissions a plugin has no database, network or file access; with them it reaches only its own data and the addresses it lists.

4. Plugin blocks in pages

A plugin can add a kind of block to pages, such as a progress bar, a chart or a status badge. It declares a screen for the content.macro slot in its package. While the plugin is active, the editor's / menu lists one item per such screen, labelled with the screen's name; see Macros for how writers use them.

  • What a block stores: which plugin and screen draws it, its parameters (a JSON object, at most 8 KB) and one line of text (at most 1,000 characters) for readers who can't see the plugin's frame and for search. A page holds at most 50 plugin blocks.
  • Where it's drawn: in the reading view and the editor, in a sandboxed frame that gets only the block's parameters. In the editor the frame can change its own block's parameters and text, only right after the writer acted in it.
  • When the text shows instead: while the plugin is inactive or uninstalled, for a screen the plugin no longer has, for readers who aren't signed in, inside included pages, in exports, and past the first 20 blocks of a page.
  • Search: when a page is published, each active plugin that answers wiki_pages.macro_render is asked once for each of its own blocks and gives back text search should find. At most 20 calls, 2 seconds each, 5 seconds in all. A slow or failing plugin never stops the publish.

The Wiki's sample plugin progress-bar shows how: it adds a Progress bar block, asks only for services:provide and answers wiki_pages.macro_render with the bar's label and percentage.

5. Services

A plugin that lists a service under provides and has services:provide is asked by the Wiki when the feature needs it:

ServiceWhen it's askedWhat it gets and answers
wiki_pages.macro_renderA page with the plugin's blocks is publishedThe block's screen and parameters (nothing about the page, the space or the person publishing); answers plain text for search. It should answer empty text, not an error, for parameters it can't read
wiki_imports.macroA space is imported from another wiki (Confluence import) and a macro isn't converted by the Wiki itselfThe macro's name, parameters and body as the other wiki stored them (at most 64 KB; nothing about the page, the space or the person importing); answers one of its own content.macro screens and parameters to draw it with, plain text, or nothing when the macro isn't its own. 2 seconds per call and 30 seconds per import

Activating a plugin that answers wiki_imports.macro lets it see the bodies of macros in every import from then on. A macro no plugin converts stays in the page as an imported macro, shown as text.

6. Signing and trust

Every package is signed. The Wiki checks the signature when you upload a plugin and every time a server loads it; removing a key under Trusted signing keys stops the plugins it signed on all servers.

With PLUGIN_SIGNING_REQUIRED=false, unsigned or untrusted packages can still be installed. They are marked Untrusted everywhere they appear. Only turn this off for development.

A plugin that keeps data has a permanent id (for example com.example.charts). The first install ties the id to the key that signed it, so a package signed by someone else can never take over that plugin's data.

7. What people see

When a plugin blocks an action, the person sees the plugin's name and its message. If a plugin fails or takes too long while checking an action, the action goes ahead, except for security-sensitive actions (such as signing in) and actions the event marks as closed on failure (such as publishing a page), which are refused.

8. Plugin screens

A plugin can bring its own screens. They are declared in its package and appear only while the plugin is active; deactivating or uninstalling it removes them everywhere at once. Each screen runs in a sandboxed frame styled like the Wiki, sees nothing but what the host hands it, and may show only to people with the permission the plugin names for it.

WhereWhat a plugin can add
Pages (content.macro)A block writers insert from the editor's / menu (see Plugin blocks in pages)
A space's Blog tab (blog.sidebar)A panel beside the posts, under the drafts and the archive. It is told the space and the month shown, and is drawn for everyone who reads the blog
Left nav → PluginsA full page of its own, listed as a sub-item (/plugins/<plugin>); the plugin draws everything but the left and top nav
DashboardA widget
Profile menu, Profile → settingsA menu entry that opens a dialog; a section in the Access group of your profile settings
Settings → Plugins, a settings page of its ownA section on that page, or a page under Settings
The plugin's own pageA panel with its feature's controls
The setup guideA step of its own after activation

The Wiki itself never draws a screen for one particular plugin: everything a plugin's feature needs is a screen of that plugin. Secrets the host makes for a plugin screen (a key, for example) are shown by the Wiki in its own dialog and never handed to the frame, and risky changes are confirmed by the Wiki before they happen.

9. Data, network and secrets

The plugin's page has a tab for each screen the plugin adds there, then Settings (its secrets, settings and call limits) and Details (who made and signed it, the permissions it was approved for, the screens it adds and where people find them, the events it receives, the services it answers, its id, the limits it runs with, how much storage it uses and the web addresses it called on this server). A deactivated plugin can be activated again from the top of its page; it keeps the permissions it was approved for.

  • Database (db:own): each plugin gets its own Postgres schema and login, set up when it is activated. Its tables are created by the migrations in its package, also on upgrades; a migration that fails refuses the upgrade and the old version keeps running. It can't see the Wiki's tables or another plugin's. When it goes over its storage quota, super admins get an alert and the plugin can only read and delete until it's back under.
  • Key-value store (kv:own): keys with an expiry, limited in number and size. With Redis they are shared by every server; on a single server without Redis they are kept in memory and lost on restart.
  • Outbound calls (net:outbound): only to the https addresses in its package (*. matches subdomains), checked again on every redirect. Private and internal network addresses are refused. PLUGIN_EGRESS=false blocks every plugin request; with PLUGIN_EGRESS_PROXY requests go through your proxy, which then decides what is reachable.
  • Secrets: a plugin can declare secrets (for example an access token for a web service). Administrators set them on the plugin's page. The Wiki adds them as a header to requests to the hosts the secret names; the plugin never sees the value, and it is never shown again.
  • Limits: a plugin can ask for less memory, a shorter time limit, fewer calls at once and fewer calls per second (across the cluster with Redis) than the installation allows; asking for more gives it the installation's limit. The page shows what it runs with.

Data survives restarts, deactivating and upgrades. It is deleted only when an administrator chooses it and types the plugin's name:

  • Restart offers Also delete its data: the database and keys are emptied and set up again (secrets are kept).
  • Uninstall asks whether to keep or delete the data. Kept data appears under Settings → Plugins → Leftover data, where you can delete it later; installing the same plugin again picks it up.

Before using db:own: the Wiki's database role (or the one in PLUGIN_DATABASE_URL) needs CREATEROLE and CREATE on the database, and pg_hba.conf must allow password (SCRAM) logins for the plugin roles, which are named plg_*. Activation is refused with a clear message when it doesn't.

10. Plugin settings

A plugin can declare settings: on/off switches, text, numbers with a range, or a choice from a list, each with a default. Administrators change them on the plugin's Settings tab; every call the plugin handles gets the current values. An upgrade keeps them, uninstalling removes them. Settings aren't for passwords or tokens: use secrets for those.

11. Health and restarts

A plugin's page shows how it's doing on the server you're using: working, failing, or paused with its last error. A plugin that fails PLUGIN_BREAKER_FAILURES calls in a row (5 by default) is paused on that server for PLUGIN_BREAKER_COOLDOWN (60 s), and super admins get an alert. While paused, checks follow the action's usual rule for a failing plugin, reactions are retried later, and services are skipped (a published page then gets no search text from its blocks). One successful call after the pause ends it.

Restart (plugins:admin) loads an active plugin again on every server, with fresh copies and its failure count cleared.

12. Performance

  • Plugins that check actions run while the person waits. All plugins on one action together must finish within PLUGIN_PREHOOK_TIMEOUT (5 s by default); slow plugins make every such action slower.
  • Plugins that react after an action run in the background and are retried if they fail.
  • Each plugin uses up to PLUGIN_MAX_MEMORY (64 MiB) per running copy, and each server keeps up to PLUGIN_INSTANCES (2) copies per plugin.
  • All plugins together run at most PLUGIN_MAX_CONCURRENT calls at once on a server (half its processors, at least 2), so a plugin that hangs can't use every processor.

13. Clusters

Packages are stored in the configured file storage, so every server loads the same plugins. Clusters need shared storage (S3, MinIO, Azure, or a shared volume). Changes take effect immediately with Redis, and within PLUGIN_CACHE_TTL (10 s) without it. Plugin databases, settings and secrets live in Postgres and key-value data in Redis, so every server sees the same data. If Redis is lost in a cluster, key-value calls fail rather than give servers different answers.

14. Building a plugin

A plugin is a folder with plugin.yaml and a WebAssembly module built as a WASI reactor; screens are HTML pages in its ui/ folder. This is the sample block plugin's manifest:

# plugin.yaml
name: progress-bar
version: 1.0.0
type: embedded
description: Adds a progress bar people insert from the wiki editor's "/" menu.
author: Example Ltd
permissions:
  - services:provide
provides:
  - wiki_pages.macro_render
ui:
  slots:
    - id: bar
      slot: content.macro
      label: {en: Progress bar, de: Fortschrittsbalken}
      entry: ui/index.html

A plugin that checks an action names the event and phase under hooks:

# plugin.yaml (excerpt)
permissions: [events:intercept]
hooks:
  - {event: page.publish, phase: before, priority: 10}

Package and sign it with the pluginpack tool:

pluginpack keygen -out keys                     # once: keys/signing.key (secret), keys/signing.pub (trust this)
pluginpack pack -dir . -key keys/signing.key -out progress-bar.zip
FieldMeaning
name3–64 lowercase letters, digits and dashes; unique per server
versionSemantic version, such as 1.2.0
idPermanent id such as com.example.charts; required with db:own or kv:own. Never change it: its data is tied to it
hooksEvents to receive: phase: before (needs events:intercept, only for events that can be blocked) or after (needs events:subscribe); priority 0–1000, lower runs first
providesServices it answers (needs services:provide): wiki_pages.macro_render, wiki_imports.macro
resourcesMemory, time limit, calls at once and calls per second, within the installation's limits
storagedatabase (migrations folder, quota, statement time limit, connections, rows) and kv (keys, value size, longest expiry)
network.outboundThe https addresses it may call
secretsValues administrators set, added as a header for the hosts listed; required, placeholder and helpUrl work as for settings
settingsUp to 30 options: boolean, string (with maxLength), integer (with min/max) or choice (with options), each with a default; required: true needs a value saved before activation
docsUrlThe plugin's documentation (https), linked from the setup guide
ui.slotsThe plugin's screens: each with an id, a slot (content.macro, blog.sidebar, nav.page, dashboard.widget, profile.menu, profile.settings, settings.page, settings.section with its page, plugin.details, setup.step), a label per language, an optional icon, the entry page under the package's ui/ folder, and optionally the permission a viewer needs. A package whose entries are missing is refused
iconThe plugin's own icon: an SVG file in the package's ui/ folder, at most 32 KB, drawn in one colour that follows the theme. Plain shapes only: a file with scripts, event attributes, embedded images or links is refused on install
mobilefalse when the plugin's screens don't work on small screens: on phones its page, menu items and dashboard widgets are then hidden, and Settings → Plugins marks it Desktop only. Default true

Screens load ./sdk.js (pluginpack adds it) and talk to the Wiki through it: they get the theme, language and context (for a block: whether it's being read or edited, and its parameters), call the host methods their approved permissions allow, and never see a secret. A block's frame in the editor has one host method, macro.update, to change its parameters and text.

Before-hooks get the action's details (never passwords or secrets) and return allow, deny with a message, or modify with new values (only the fields the event allows are kept). After-hooks get the result; returning an error retries the event later, so make them safe to run twice (deliveryId stays the same on retries).

15. API

MethodEndpointPermissionDescription
GET/api/pluginsplugins:readInstalled plugins
POST/api/pluginsplugins:adminUpload a package (multipart field package)
GET/api/plugins/{name}readOne plugin, with its limits, data usage, secrets (set or not) and health
GET/api/plugins/{name}/setupadminWhat it still needs: {complete, steps: [{id, kind, status, required, reason}]}
POST/api/plugins/{name}/activateadmin{"permissions": [...]}: all the permissions it asks for
POST/api/plugins/{name}/deactivateadminStop it
POST/api/plugins/{name}/restartadminLoad an active plugin again on every server; {"resetData": true, "confirm": "<name>"} also empties its data
DELETE/api/plugins/{name}adminUninstall; a plugin with data needs {"deleteData": true|false} and, to delete, "confirm": "<name>"
PUT / DELETE/api/plugins/{name}/secrets/{secret}adminSet {"value"} / remove a secret
PUT/api/plugins/{name}/settingsadminIts settings (null resets one)
GET/api/plugins/uisigned inThe screens of active plugins you may see, by slot
GET/api/plugin-ui/{name}/{file}—An active plugin's screen files, served sandboxed
GET/api/plugins/dataadminLeftover data
DELETE/api/plugins/data/{key}admin{"confirm": "<plugin name>"}: delete leftover data
GET / POST/api/plugins/trusted-keysadminList / add {name, publicKey} (PEM)
DELETE/api/plugins/trusted-keys/{id}adminStop trusting a key

A blocked action returns 403 with "reason": "plugin_denied" and the plugin's name and message in details. Activating a plugin whose required secrets or settings aren't set returns 422 plugin_setup_required, with the missing ones in details.secrets and details.settings.

16. Events

EventWhen
plugin.data.deleteA plugin's data is deleted: uninstalled with its data, restarted with its data reset, or its leftover data deleted. Policies can refuse it
plugin.settings.updateA plugin's settings or call limits change

Both can be refused by policies, and are refused if a check fails. See Events.

17. Settings

VariableDefaultDescription
PLUGIN_SIGNING_REQUIREDtrueReject packages not signed by a trusted key (false: install them as untrusted)
PLUGIN_TRUST_STORE_PATH—Folder of public keys trusted on this server, in addition to keys added in Settings
PLUGIN_MAX_MEMORY67108864Memory per plugin copy, in bytes
PLUGIN_INSTANCES2Copies per plugin per server (how many calls run at once)
PLUGIN_MAX_PACKAGE_SIZE20971520Largest package accepted, in bytes
PLUGIN_PREHOOK_TIMEOUT5sTime limit for checking one action
PLUGIN_EXEC_TIMEOUT30sTime limit for reacting to one event
PLUGIN_CACHE_TTL10sHow quickly servers pick up plugin changes without Redis
PLUGIN_MAX_CONCURRENThalf the processors, at least 2Plugin calls running at once on a server, all plugins together
PLUGIN_BREAKER_FAILURES5Failures in a row that pause a plugin on a server
PLUGIN_BREAKER_COOLDOWN60sHow long a paused plugin stays paused
PLUGIN_MAX_CALLS_PER_SECOND100Most calls per second a plugin may ask for (and its default)
PLUGIN_MAX_HOST_CALLS1000Database, key-value and web requests one plugin call may make
PLUGIN_DATABASE_URLthe Wiki's databasePostgres for plugin schemas; its role needs CREATEROLE and CREATE on the database
PLUGIN_DB_MAX_QUOTA1073741824Largest storage quota per plugin, in bytes (and the default)
PLUGIN_DB_STATEMENT_TIMEOUT5sLongest time one plugin statement may run (and the default)
PLUGIN_DB_MAX_CONNECTIONS4Most database connections per plugin per server (default 2)
PLUGIN_DB_MAX_ROWS1000Most rows one query returns (and the default)
PLUGIN_DATA_CHECK_INTERVAL5mHow often plugin storage is measured against quotas and pending deletions are retried
PLUGIN_KV_MAX_KEYS100000Most keys per plugin (default 10000)
PLUGIN_KV_MAX_VALUE262144Largest value, in bytes (and the default)
PLUGIN_KV_MAX_TTL168hLongest key expiry (and the default)
PLUGIN_EGRESStruefalse blocks every plugin web request
PLUGIN_EGRESS_PROXY—Send plugin web requests through this HTTP proxy
PLUGIN_HTTP_ALLOW_HTTPfalseAllow plain http:// addresses (development only)
PLUGIN_HTTP_ALLOW_PRIVATEfalseAllow private and loopback addresses (development only)
PLUGIN_HTTP_TIMEOUT10sTime limit per plugin web request
PLUGIN_HTTP_MAX_RESPONSE2097152Largest response a plugin receives, in bytes