Servers
API reference for servers, enrollment tokens and agent install commands, metrics history, agent updates, terminal sessions and the dashboard summary.
A server is a machine the panel manages through its agent. Adding one creates a record in pending state and a one-time enrollment token; the server becomes online once its agent registers and reports in. See Connecting servers.
Operations on a server (restarting a service, rebooting, listing processes) are queued as jobs with POST /servers/:id/jobs.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/servers | List servers |
| POST | /api/v1/servers | Add a server |
| GET | /api/v1/servers/:id | Get a server |
| PATCH | /api/v1/servers/:id | Rename a server |
| DELETE | /api/v1/servers/:id | Remove a server |
| POST | /api/v1/servers/:id/enrollment-tokens | Create an enrollment token |
| GET | /api/v1/servers/:id/metrics | Get metrics history |
| POST | /api/v1/servers/:id/jobs | Queue an operation (on the Jobs page) |
| PUT | /api/v1/servers/:id/groups | Set a server's groups |
| POST | /api/v1/servers/:id/agent-update | Update the agent |
| POST | /api/v1/servers/:id/terminal | Open a terminal |
| GET | /api/v1/terminal-sessions | List terminal sessions |
| GET | /api/v1/terminal-sessions/:id | Get a terminal session |
| GET | /api/v1/terminal-sessions/:id/recording | Download a recording |
| DELETE | /api/v1/terminal-sessions/:id | Delete a recording |
| GET | /api/v1/terminal-sessions/settings | Get recording settings |
| PUT | /api/v1/terminal-sessions/settings | Change recording settings |
| GET | /api/v1/dashboard | Get the dashboard summary |
The server object
{
"id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
"name": "web-1",
"status": "online",
"isLocal": false,
"hostname": "web-1",
"publicIp": "203.0.113.10",
"os": { "name": "Ubuntu", "version": "24.04", "kernel": "6.8.0-48-generic", "architecture": "x64" },
"cpuCores": 4,
"memoryTotalBytes": 8336568320,
"diskTotalBytes": 168488570880,
"uptimeSeconds": 1209600,
"timezone": "Etc/UTC",
"agentVersion": "0.41.0",
"lastSeenAt": "2026-11-10T11:05:30.000Z",
"services": [
{ "name": "nginx", "loadState": "loaded", "active": "active", "sub": "running", "enabled": "enabled", "description": "A high performance web server and a reverse proxy server" }
],
"filesystems": [{ "mount": "/", "device": "/dev/sda1", "fsType": "ext4", "totalBytes": 168488570880, "usedBytes": 41203298304 }],
"agentOperations": ["SERVICE_STATUS", "SERVICE_RESTART", "PROCESS_LIST", "SERVER_REBOOT"],
"webStack": { "nginx": true, "certbot": true, "git": true, "mariadb": true, "phpVersions": ["8.3"] },
"selfCheck": null,
"ipAddresses": ["203.0.113.10"],
"customerDns": { "nameservers": [], "autoZones": false },
"createdAt": "2026-10-20T08:10:00.000Z",
"updatedAt": "2026-11-10T11:05:30.000Z"
}| Field | Description |
|---|---|
status | pending (no agent yet), online, offline (the agent stopped reporting) or disabled. |
isLocal | The server the panel itself runs on, connected automatically. |
services, filesystems | The agent's latest snapshot, sent with every heartbeat. |
agentOperations | The operations this agent reports it supports. Queuing anything else answers 409 AGENT_OUTDATED. |
webStack | What the agent found installed, such as NGINX, Certbot, Git, MariaDB and the PHP versions. The example shows some of its fields. null until reported. |
selfCheck | The agent's last self-check report (agent 0.39.0 and later), or null. |
timezone | The server's own time zone, which cron jobs run in. |
customerDns | The name servers hosting customers on this server are shown, and whether their domains get DNS zones automatically. |
List servers
/api/v1/serversServers, newest first, each with its latest metrics, its groups and whether a newer agent is available. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Matches name, host name or public IP. |
status | string | No | pending, online, offline or disabled. |
groupId | string | No | Only servers in this group. |
sort | string | No | createdAt (default), name or lastSeenAt. |
Example request
curl "https://panel.example.com/api/v1/servers?status=online" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.servers.list({ status: 'online' });Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
"name": "web-1",
"status": "online",
"latestMetrics": {
"collectedAt": "2026-11-10T11:05:30.000Z",
"cpuPercent": 12.4,
"load": [0.42, 0.38, 0.35],
"memoryUsedBytes": 3221225472,
"memoryTotalBytes": 8336568320,
"swapUsedBytes": 0,
"swapTotalBytes": 2147483648,
"diskUsedBytes": 41203298304,
"diskTotalBytes": 168488570880,
"netRxBytesPerSec": 18234,
"netTxBytesPerSec": 9120,
"processCount": 187,
"uptimeSeconds": 1209600
},
"groups": [{ "id": "c2d4…", "name": "Production", "color": "green" }],
"agentUpdateAvailable": false
}
],
"pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
},
"message": "OK",
"requestId": "…"
}Each item carries every field of the server object; the example shows only the fields lists add.
Add a server
/api/v1/serversCreates a server record and its first enrollment token. Run the returned install command on the server, as root, to install and register the agent. The token is valid for 60 minutes by default (VAULTPANEL_ENROLLMENT_TTL_MINUTES) and only once.
When the panel serves its own self-signed certificate, the command carries the certificate's public key pin, so the agent trusts exactly that certificate.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 100 letters, numbers, spaces and . _ - ( ). |
Example request
curl https://panel.example.com/api/v1/servers \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"web-2"}'const { server, enrollment } = await panel.servers.create({ name: 'web-2' });
console.log(enrollment.installCommand);Response 201 Created
{
"success": true,
"data": {
"server": { "id": "4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f", "name": "web-2", "status": "pending", "agentVersion": null, "createdAt": "…" },
"enrollment": {
"token": "vpe_…",
"expiresAt": "2026-11-10T12:10:00.000Z",
"installCommand": "curl -fsSL --pinnedpubkey 'sha256//…' -k https://panel.example.com/api/v1/agent/install.sh | sudo bash -s -- --panel https://panel.example.com --token vpe_… --panel-pin 'sha256//…'"
}
},
"message": "Server added. Run the install command on it to connect the agent.",
"requestId": "…"
}Errors
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | You lack servers.manage. |
| 422 | VALIDATION_ERROR | The name is missing or has characters that are not allowed. |
Get a server
/api/v1/servers/:idThe server with its latest metrics, groups, registered agent, any unused enrollment token and agent update information.
Example request
curl https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const server = await panel.servers.get(serverId);Response 200 OK. The server object plus:
{
"latestMetrics": { "collectedAt": "…", "cpuPercent": 12.4 },
"groups": [{ "id": "c2d4…", "name": "Production", "color": "green" }],
"agent": {
"id": "b7c8…",
"keyFingerprint": "SHA256:…",
"version": "0.40.0",
"registeredAt": "2026-10-20T08:12:44.000Z",
"registeredIp": "203.0.113.10",
"lastSeenAt": "2026-11-10T11:05:30.000Z"
},
"pendingEnrollment": null,
"agentUpdate": {
"currentVersion": "0.40.0",
"latestVersion": "0.41.0",
"fromPanel": true,
"command": "curl -fsSL … | sudo bash -s -- --upgrade --panel https://panel.example.com …"
}
}agentUpdate is null when the agent is current. fromPanel says whether Update the agent can do it; otherwise run command on the server. pendingEnrollment holds the expiry of an unused token.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such server. |
Rename a server
/api/v1/servers/:idRequest body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 100 letters, numbers, spaces and . _ - ( ). |
Example request
curl -X PATCH https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"web-1 (Frankfurt)"}'const server = await panel.servers.update(serverId, { name: 'web-1 (Frankfurt)' });Response 200 OK with the server, as from Get a server.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such server. |
| 422 | VALIDATION_ERROR | The name is invalid. |
Remove a server
/api/v1/servers/:idRemoves the server from the panel, revokes its agent, invalidates its enrollment tokens and cancels its queued jobs. Nothing on the server itself is touched; the agent stops working once revoked.
Example request
curl -X DELETE https://panel.example.com/api/v1/servers/4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.servers.remove(serverId);Response 200 OK
{ "success": true, "data": null, "message": "Server removed and its agent revoked", "requestId": "…" }Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such server. |
Create an enrollment token
/api/v1/servers/:id/enrollment-tokensIssues a new enrollment token and install command for a server, for example when the first one expired. Only the newest token works: older unused ones stop working.
Example request
curl -X POST https://panel.example.com/api/v1/servers/4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f/enrollment-tokens \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { token, expiresAt, installCommand } = await panel.servers.enrollmentToken(serverId);Response 201 Created
{
"success": true,
"data": { "token": "vpe_…", "expiresAt": "2026-11-10T12:20:00.000Z", "installCommand": "curl -fsSL … | sudo bash -s -- --panel https://panel.example.com --token vpe_…" },
"message": "New enrollment token created; older ones no longer work",
"requestId": "…"
}Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such server. |
Get metrics history
/api/v1/servers/:id/metricsCPU, memory, swap, disk, network and process history. Short ranges return the agent's raw 15-second samples, averaged down to at most 240 points. Long ranges return hourly rollups, which add the hour's highest CPU and the number of samples.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
range | string | No | 1h (default), 6h, 24h (raw), or 7d, 30d, 90d (hourly). |
Example request
curl "https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/metrics?range=7d" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { resolution, points } = await panel.servers.metrics(serverId, { range: '7d' });Response 200 OK
{
"success": true,
"data": {
"range": "7d",
"resolution": "hour",
"points": [
{
"collectedAt": "2026-11-03T12:00:00.000Z",
"cpuPercent": 9.8,
"cpuPercentMax": 41.2,
"samples": 240,
"load": [0.31, 0.29, 0.27],
"memoryUsedBytes": 3105423360,
"memoryTotalBytes": 8336568320,
"swapUsedBytes": 0,
"swapTotalBytes": 2147483648,
"diskUsedBytes": 40961949696,
"diskTotalBytes": 168488570880,
"netRxBytesPerSec": 15022,
"netTxBytesPerSec": 8411,
"processCount": 184,
"uptimeSeconds": null
}
]
},
"message": "OK",
"requestId": "…"
}resolution is raw for 1h, 6h and 24h, and hour otherwise. Raw points have no cpuPercentMax or samples.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such server. |
| 422 | VALIDATION_ERROR | range is not one of the values above. |
Set a server's groups
/api/v1/servers/:id/groupsReplaces the list of groups a server is in. An empty list takes it out of every group.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
groupIds | string[] | Yes | Up to 50 group ids. |
Example request
curl -X PUT https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/groups \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"groupIds":["c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e"]}'const groups = await panel.request('PUT', `/servers/${serverId}/groups`, { body: { groupIds: [groupId] } });Response 200 OK
{ "success": true, "data": [{ "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e", "name": "Production", "color": "green" }], "message": "Groups saved", "requestId": "…" }Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | One of the groups was not found. |
| 422 | VALIDATION_ERROR | The server was not found, or an id is not a UUID. |
Update the agent
/api/v1/servers/:id/agent-updateQueues an AGENT_UPDATE job that installs the agent version this panel serves, checked against its SHA-256. Agents 0.7.0 and later can update themselves this way; older agents need the agentUpdate.command from Get a server run on the server. To update many servers at once, use a bulk action.
Example request
curl -X POST https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/agent-update \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.servers.updateAgent(serverId);
await panel.jobs.wait(job.id);Response 202 Accepted with the job, message Agent update queued.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such server. |
| 409 | AGENT_CURRENT | The agent is already on the newest version. |
| 409 | AGENT_OUTDATED | The agent is too old to update itself. Run the upgrade command on the server. |
| 409 | SERVER_NOT_READY | The server has no connected agent yet. |
| 409 | DUPLICATE_OPERATION | An update is already queued or running (details.jobId). |
Open a terminal
/api/v1/servers/:id/terminalIssues a one-time ticket for a root terminal on the server. The browser then opens a WebSocket at the returned path within 30 seconds. Only owners have servers.terminal, and the terminal opens only from a browser session: API tokens, plugins and the AI assistant are always refused. Every session is audited and, by default, recorded. Needs agent 0.11.0 or later.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
cols | integer | No | Terminal width, 2 to 1000. Default 80. |
rows | integer | No | Terminal height, 2 to 500. Default 24. |
Example request
const res = await fetch(`/api/v1/servers/${serverId}/terminal`, {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
body: JSON.stringify({ cols: 120, rows: 32 }),
});
const { data } = await res.json();
const socket = new WebSocket(`wss://${location.host}${data.path}`);Response 201 Created
{ "success": true, "data": { "ticket": "…", "path": "/api/v1/terminal/connect?ticket=…", "expiresInSeconds": 30 }, "message": "OK", "requestId": "…" }Errors
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | You are not an owner, or the request did not come from a browser session. |
| 404 | NOT_FOUND | No such server. |
| 409 | SERVER_OFFLINE | The server is not online. |
| 409 | AGENT_TOO_OLD | The agent is older than 0.11.0. |
| 409 | TERMINAL_NOT_CONNECTED | The agent has not connected its terminal channel yet. Try again in a few seconds. |
| 409 | TERMINAL_DISABLED | The terminal is turned off on this server. |
| 429 | TOO_MANY_TERMINALS | 5 terminals are open on this server, or 10 are open for you. |
Terminal sessions
Past terminal sessions and their recordings, in asciicast format. Like the terminal itself these need servers.terminal, so in practice an owner's browser session. See Terminal.
The session object
{
"id": "e3f1a2b4-…",
"serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
"serverName": "web-1",
"userId": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07",
"userLabel": "ada@example.com",
"ip": "198.51.100.24",
"cols": 120,
"rows": 32,
"startedAt": "2026-11-10T10:00:02.000Z",
"endedAt": "2026-11-10T10:12:47.000Z",
"seconds": 765,
"exitCode": 0,
"endReason": "exit",
"outputBytes": 48211,
"recording": "output",
"recordingBytes": 51002,
"recordingTruncated": false
}recording is off, output or output_input (keystrokes too).
List terminal sessions
/api/v1/terminal-sessionsQuery parameters
| Name | Type | Required | Description |
|---|---|---|---|
page, pageSize | integer | No | Paging, as for other lists. |
serverId | string | No | Sessions on one server. |
userId | string | No | Sessions of one person. |
Response 200 OK: { items: [session], pagination }.
Get a terminal session
/api/v1/terminal-sessions/:idResponse 200 OK with the session object. 404 NOT_FOUND when there is no such session.
Download a recording
/api/v1/terminal-sessions/:id/recordingStreams the recording as application/x-asciicast. Add ?download=1 to receive it as an attachment named after the server and start time.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such session, it was not recorded, or the file was removed after the retention period. |
Delete a recording
/api/v1/terminal-sessions/:idDeletes a closed session's recording.
Response 200 OK with data: null, message Recording deleted.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such session. |
| 409 | SESSION_OPEN | The session is still open. |
Get recording settings
/api/v1/terminal-sessions/settingsResponse 200 OK
{ "success": true, "data": { "enabled": true, "recordInput": false, "retentionDays": 90, "maxSizeMb": 50 }, "message": "OK", "requestId": "…" }The values shown are the defaults.
Change recording settings
/api/v1/terminal-sessions/settingsRequest body
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | Yes | Record new sessions. |
recordInput | boolean | Yes | Also record what is typed (passwords typed at prompts included). |
retentionDays | integer | Yes | 1 to 3650. Older recordings are deleted. |
maxSizeMb | integer | Yes | 1 to 1024. A longer session's recording is truncated. |
Response 200 OK with the saved settings, message Terminal recording settings saved.
Get the dashboard summary
/api/v1/dashboardCounts for the panel's dashboard. Each section is filled only when you have the permission to see it, and is null otherwise.
Example request
curl https://panel.example.com/api/v1/dashboard \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const summary = await panel.dashboard();Response 200 OK
{
"success": true,
"data": {
"servers": { "total": 3, "byStatus": { "pending": 0, "online": 3, "offline": 0, "disabled": 0 } },
"websites": { "total": 6, "byStatus": { "active": 6 }, "sslExpiring": 0 },
"applications": { "total": 2, "busy": 0, "byProcess": { "running": 2 }, "deployments24h": { "succeeded": 3 } },
"databases": { "total": 4, "byStatus": { "active": 4 }, "users": 4 },
"backups": { "byStatus": { "succeeded": 28 }, "failedLastDay": 0, "schedules": 3, "totalBytes": 1873420288 },
"cron": { "jobs": 5, "failedLastDay": 0 },
"jobs": { "last24h": { "succeeded": 41, "failed": 1 } },
"recentJobs": [],
"recentActivity": [],
"users": { "active": 5 },
"alerts": { "firing": 0, "unacknowledged": 0, "bySeverity": {} }
},
"message": "OK",
"requestId": "…"
}| Section | Needs |
|---|---|
servers | servers.read |
websites, applications, databases, backups, cron | The matching .read permission |
jobs, recentJobs | jobs.read (the 6 most recent jobs, routine ones left out) |
recentActivity | audit.read (the 8 most recent audit log entries) |
alerts | alerts.read |
users | users.read |
Panel settings
API reference for the panel's own settings - putting the panel on a domain, its address, and the email it sends for invites, password resets and alerts.
Jobs
API reference for jobs, the asynchronous record of every change an agent makes, and the catalog of operations you can queue on a server.