Plugins
Extend VaultPanel with plugins — separate programs that call the API with their own token, receive signed events and add a page to the panel's sidebar.
A plugin adds a feature to VaultPanel or connects it to an outside service (a status page, a chat bot, an inventory, a billing or ticketing system) without changing the panel's code.
A plugin is a separate program, run wherever its author likes: on the panel's server, on another server or as a hosted service. It works with the panel in three ways, and only these:
- It calls the REST API with its own token (
vpp_…), limited to the permissions an owner or admin approved when installing it. - It receives panel events (deployments, alerts, backups, servers going offline) at its
webhookUrl, signed with its own secret. - It can show a page inside the panel, listed in the sidebar and opened with a signed link that tells the plugin who is looking.
A plugin never runs inside the panel's process, never adds agent operations and never runs commands on a server itself. Anything it changes goes through the same API, permission checks, job queue and audit log as a person using the panel.
Installing a plugin
Open Plugins (under System) and click Install plugin, or pick one on the Directory tab. Give the plugin's manifest URL (the panel fetches it) or paste the manifest as JSON.
The panel explains what the plugin asks for in words: each permission scope, the events, its page, and warnings (plain http, server operations, customer management). Approving installs it and shows the plugin's token and signing secret once; give both to the plugin. The panel keeps only the token's SHA-256 and an encrypted copy of the secret.
Installing, updating and making new credentials need plugins.manage (owners and admins) and a person signed in to the panel: they are refused for API tokens and for plugins. Listing, turning a plugin on or off, removing it and its events also work with a full API token. A panel can have up to 50 plugins.
| On the plugin's page | Does |
|---|---|
| Turn off / on | Off: its token is refused (401), it receives no events and its page is hidden. On again restores it. |
| Events | Every event sent to it, with the response; Send test event; Send again. |
| Settings > Update | Reads the manifest URL again (or a pasted manifest), shows what changed and asks for approval again. |
| Settings > Make new credentials | A new token and secret; the old ones stop working at once. |
| Settings > Remove | Deletes the plugin, its token and its events. What it already did in the panel stays. |
The manifest
{
"manifestVersion": 1,
"id": "status-board",
"name": "Status Board",
"version": "1.0.0",
"description": "Every server at a glance, with the latest deployments and alerts.",
"author": "Example Ltd",
"homepage": "https://example.com/status-board",
"permissions": ["read"],
"events": ["server.offline", "server.online", "deployment.failed"],
"webhookUrl": "https://status.example.com/events",
"page": { "title": "Status board", "url": "https://status.example.com/", "icon": "activity" }
}| Field | Rules |
|---|---|
manifestVersion | 1 |
id | 3 to 64 lowercase letters, digits and dashes, starting with a letter and not ending with a dash. Unique per panel; an update must keep it. |
name | Up to 100 characters. |
version | Up to 32 characters. |
description | Optional, up to 500 characters. |
author | Optional, up to 100 characters. |
homepage | Optional URL. |
permissions | Scopes, as for API tokens: read, logs, deploy, manage, servers, customers. Not full: a plugin can never manage users, roles, panel settings or plugins. |
events | Any of the events. Needs webhookUrl. |
webhookUrl | Where events are POSTed. |
page | Optional. title (up to 60 characters), url, and icon: one of plug, activity, gauge, bell, server, globe, app, database, shield, card, briefcase, users, logs, zap, sparkles, package, layers, containers, automation. |
Unknown fields are refused, so a misspelt permission is an error rather than silently ignored. A manifest fetched by URL may be up to 64 KB.
Calling the API
Send the token as a Bearer token, exactly like an API token. With the SDK:
import { VaultPanel } from '@vaultpanel/sdk';
const panel = new VaultPanel({
baseUrl: 'https://panel.example.com',
token: process.env.VAULTPANEL_PLUGIN_TOKEN,
});
const { items } = await panel.servers.list();GET /api/v1/auth/mereturns{ user: null, plugin: { id, slug, name, scopes }, permissions }.- Every call is audited with the actor
plugin:<id>; a refused call is audited asauthz.denied. Jobs it starts show as queued by the plugin. - A plugin cannot use the rest of
/auth, create API tokens, or read or change plugins.
Events
Each event needs a permission the plugin's scopes include, so a plugin never hears about something it could not read through the API. All of them are covered by read.
| Events | Need |
|---|---|
server.offline, server.online | servers.read |
alert.firing, alert.resolved | alerts.read |
deployment.succeeded, deployment.failed | applications.read |
backup.succeeded, backup.failed, restore.succeeded, restore.failed | backups.read |
cron.failed | cron.read |
ssl.expiring, ssl.expired, ssl.renew_failed | websites.read |
Receiving events
Each event is a POST to webhookUrl with a JSON body:
{ "id": "delivery id", "event": "server.offline", "occurredAt": "2026-10-05T18:00:00.000Z", "data": { "server": { "id": "…", "name": "web-1" } } }| Header | Value |
|---|---|
X-VaultPanel-Event | The event. |
X-VaultPanel-Delivery | The delivery id, the same on every retry. |
X-VaultPanel-Timestamp | Unix seconds. |
X-VaultPanel-Signature | sha256= followed by the hex HMAC-SHA256 of <timestamp>.<raw body> with the signing secret. |
X-VaultPanel-Plugin | The plugin's id. |
Answer with any 2xx. Anything else, or no answer within 10 seconds, is tried again after 1, 5 and 30 minutes. Send test event sends webhook.test.
Verifying the signature
Check the signature before trusting an event. Pass the raw request body, before parsing it:
import { verifyEvent } from '@vaultpanel/sdk';
const event = verifyEvent({ body: rawBody, headers: req.headers, secret: process.env.VAULTPANEL_PLUGIN_SECRET });
if (!event) return res.writeHead(401).end();
// event: { id, event, occurredAt, data }import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, headers, secret) {
const timestamp = headers['x-vaultpanel-timestamp'];
const signature = headers['x-vaultpanel-signature'] ?? '';
if (!/^\d+$/.test(timestamp ?? '') || !signature.startsWith('sha256=')) return null;
// Refuse old timestamps so a captured request cannot be replayed.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return null;
const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
const given = Buffer.from(signature.slice('sha256='.length));
if (given.length !== expected.length || !timingSafeEqual(given, Buffer.from(expected))) return null;
return JSON.parse(rawBody);
}verifyEvent refuses a timestamp more than 5 minutes away (toleranceSeconds, 300 by default).
The plugin's page
A plugin's page is listed in the sidebar for people who may do everything the plugin may do (in practice, a plugin with read shows to owners and admins), so nobody gains anything by going through a plugin's page. Hosting customers never see plugin pages.
The panel shows the page in a sandboxed frame at /plugin-pages/<id>, and opens it with these query parameters added to the page URL:
| Parameter | Value |
|---|---|
vp_plugin | The plugin's id. |
vp_user, vp_email, vp_roles | Who is looking (roles comma-separated). |
vp_panel | The panel's public URL. |
vp_theme | light or dark, to match the panel. |
vp_ts | Unix seconds. |
vp_sig | Hex HMAC-SHA256, with the signing secret, of every vp_ parameter but vp_sig, sorted by name, as key=value joined by &. |
import { verifyLaunch } from '@vaultpanel/sdk';
const viewer = verifyLaunch(req.url, process.env.VAULTPANEL_PLUGIN_SECRET);
if (!viewer) return res.writeHead(403).end('Open this page from VaultPanel');
// viewer: { plugin, user: { id, email, roles }, panelUrl, theme, issuedAt }A link is good for 5 minutes; a page that stays open should start its own session once it has checked the link. The frame may run scripts, forms, pop-ups and downloads. A page on the panel's own address is shown without same-origin access, so it cannot reach the panel's session; host plugin pages on their own address.
Addresses the panel calls
The panel fetches manifests and sends events only to public addresses. The address is checked after DNS resolution, and the request goes to that same address.
| Setting | Default | Allows |
|---|---|---|
VAULTPANEL_WEBHOOK_ALLOW_PRIVATE | false on new installs | Private networks such as 10.x and 192.168.x. Panels installed before 0.2.0 keep true. |
VAULTPANEL_PLUGIN_ALLOW_LOCAL | false | Loopback (127.0.0.1), for a plugin on the panel's own server. |
Link-local and cloud metadata addresses are always refused. The page URL is opened by people's browsers, so it must be an address they can reach.
Example: Status Board
The repository's examples/status-board-plugin/server.js is a complete plugin with no dependencies beyond the SDK. It serves its manifest at /manifest.json and a one-plugin directory at /directory.json, checks and keeps the latest events, and shows every server's state and those events on its page.
Start it
PLUGIN_PUBLIC_URL=http://203.0.113.10:4100 node examples/status-board-plugin/server.jsInstall it
Install it in the panel with the manifest URL it prints, and copy the token and secret.
Restart it with the credentials
VAULTPANEL_PLUGIN_TOKEN=vpp_… VAULTPANEL_PLUGIN_SECRET=whsec_… \
PLUGIN_PUBLIC_URL=http://203.0.113.10:4100 node examples/status-board-plugin/server.js| Variable | Default | Meaning |
|---|---|---|
VAULTPANEL_URL | http://127.0.0.1:4000 | The panel's API, by default a development backend on the same machine. |
PORT | 4100 | The port the plugin listens on. |
HOST | 0.0.0.0 | The address the plugin listens on. |
PLUGIN_PUBLIC_URL | http://127.0.0.1:<PORT> | The address the panel and browsers reach the plugin at. |
PLUGIN_EVENTS_URL | PLUGIN_PUBLIC_URL | When the panel cannot reach the public address: for example http://127.0.0.1:4100, used for the manifest and events while the page keeps the public address. Needs VAULTPANEL_PLUGIN_ALLOW_LOCAL=true in the panel's .env. |
PLUGIN_VERSION | 1.0.0 | The version it reports, to try updates through its directory. |
Plugin directories
A directory is a list of plugins published as JSON at a URL by whoever maintains it: a plugin author, a hosting company, a team. Plugins > Directory > Add directory takes its URL. The panel reads it at once (nothing is saved if it cannot), then again every 12 hours, and keeps the last good copy. Up to 10 directories; none is built in.
The Directory tab lists every directory's plugins with search and categories. Install on a hosted plugin reads its manifest URL and opens the usual review; for a self-hosted plugin it links to how to run it and asks for the manifest URL of your copy. A directory only suggests: what is approved is always the plugin's own manifest, and the review warns when it asks for more than the directory listed. When a directory lists a newer version of an installed plugin, the plugin shows an update as available; Settings > Update reads the plugin's own manifest again. Removing a directory leaves the plugins installed from it installed.
{
"directoryVersion": 1,
"name": "Example Ltd plugins",
"description": "Plugins we maintain for our customers.",
"homepage": "https://example.com/plugins",
"plugins": [
{
"id": "status-board",
"name": "Status Board",
"version": "1.1.0",
"description": "Every server at a glance.",
"author": "Example Ltd",
"hosting": "hosted",
"manifestUrl": "https://status.example.com/manifest.json",
"permissions": ["read"],
"events": ["server.offline", "server.online"],
"icon": "activity",
"categories": ["monitoring"]
},
{
"id": "ticket-bridge",
"name": "Ticket Bridge",
"version": "0.3.0",
"hosting": "self-hosted",
"setupUrl": "https://example.com/plugins/ticket-bridge#run-it",
"permissions": ["read", "logs"]
}
]
}| Field | Rules |
|---|---|
directoryVersion | 1 |
name | Up to 100 characters. description (up to 500) and homepage are optional. |
plugins | Up to 500 entries. |
plugins[].id, name, version | As in the manifest. One entry per id; a repeat is left out. |
plugins[].hosting | hosted (its author runs it; needs manifestUrl) or self-hosted (you run it; needs setupUrl or homepage). Default hosted. |
plugins[].permissions, events | What it asks for, as in its manifest. |
plugins[].icon | One of the page icons. Default plug. |
plugins[].categories | Up to 5 short words. |
The file may be up to 1 MB and is fetched with the same address rules as manifests. An entry that breaks these rules is left out and shown, with the reason, under its directory. Other fields are ignored, so newer directories still work.
API
Plugins are managed under /api/v1/plugins. See the plugins API reference.
Server agent
How the VaultPanel agent works on each server — install paths, the root helper, signed jobs, its local policy in config.json, upgrades and its limits.
JavaScript SDK
Use @vaultpanel/sdk to call the VaultPanel REST API from Node.js — client options, every resource method, pagination, waiting for jobs and error handling.