Agent protocol
How the VaultPanel agent talks to the panel - enrollment, Ed25519-signed requests, heartbeats, the job long poll, signed job envelopes and result reporting.
The /agent endpoints are what the agent on each server uses to talk to the panel. They are documented for understanding and auditing how VaultPanel trusts its servers, not for building other clients: use the agent that ships with the panel. For installing and running the agent, see Agent and Connecting servers.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/agent/install.sh | The install script |
| GET | /api/v1/agent/package-rs/:arch | The agent program |
| GET | /api/v1/agent/panel-cert.pem | The panel's certificate |
| POST | /api/v1/agent/register | Register an agent |
| POST | /api/v1/agent/heartbeat | Send a heartbeat |
| GET | /api/v1/agent/jobs/next | Wait for the next job |
| POST | /api/v1/agent/jobs/:id/start | Report a job started |
| POST | /api/v1/agent/jobs/:id/logs | Send job logs |
| POST | /api/v1/agent/jobs/:id/result | Report a job's result |
| POST | /api/v1/agent/backups/:id/chunks | Send a backup for download |
| GET | /api/v1/agent/uploads/:id/chunks/:offset | Fetch an uploaded file |
| POST | /api/v1/agent/downloads/:id/chunks | Send a file for download |
| POST | /api/v1/agent/cron-runs | Report cron runs |
How the agent is trusted
- An admin adds a server. The panel creates a one-time enrollment token (stored hashed, valid for 60 minutes by default) and an install command.
- The install script downloads the agent from the panel, and the agent registers: it makes an Ed25519 key pair, sends the public key with the token, and receives its agent id and the panel's job-signing public key, which it pins.
- Every later request is signed with the agent's private key. The panel stores only the public key, checks each signature, a clock window and a single-use nonce.
- The agent connects out to the panel; servers need no inbound port. It sends a heartbeat every 15 seconds and long-polls for jobs.
- Every job is a signed envelope. The agent refuses envelopes that are unsigned, tampered with, addressed to another server, expired or already run, checks the parameters again against its own allow-list, and runs fixed commands without a shell.
Removing a server, or registering a new agent for it, revokes the old agent; a revoked agent stops. There is no endpoint that runs arbitrary commands, on the panel or the agent.
Transport
Agent endpoints from /register on require HTTPS, refused with 403 INSECURE_TRANSPORT otherwise. Plain HTTP is accepted only straight over loopback (the agent on the panel's own server, never through a proxy), or when the panel's .env sets VAULTPANEL_ALLOW_INSECURE_AGENTS for development. With the panel's self-signed certificate, the install command carries the certificate's public key pin; the agent saves the certificate as /etc/vaultpanel-agent/panel-ca.pem and trusts exactly it.
Signed requests
Every endpoint after /register needs four headers:
| Header | Value |
|---|---|
X-VaultPanel-Agent-Id | The agent id from registration (a UUID). |
X-VaultPanel-Timestamp | The time in milliseconds since the Unix epoch. |
X-VaultPanel-Nonce | 16 to 64 random URL-safe characters, never reused. |
X-VaultPanel-Signature | The base64 Ed25519 signature of the signing string. |
The signing string is five lines joined with \n: the method in capitals, the full path with its query (/api/v1/agent/heartbeat), the timestamp, the nonce, and the hex SHA-256 of the raw body (of an empty string when there is none). This is how the agent builds it:
/// METHOD, PATH, TIMESTAMP, NONCE and the body's SHA-256, joined by "
".
pub fn signing_string(method: &str, path: &str, timestamp: &str, nonce: &str, body: &[u8]) -> String {
[method.to_ascii_uppercase().as_str(), path, timestamp, nonce, sha256_hex(body).as_str()].join("
")
}
pub fn sign_request(agent_id: &str, key: &SigningKey, method: &str, path: &str, body: &[u8]) -> std::io::Result<SignedHeaders> {
let timestamp = now_ms().to_string();
// 18 random bytes as base64url: 24 characters of [A-Za-z0-9_-], never reused.
let nonce = base64url_encode(&random_bytes::<18>()?);
let message = signing_string(method, path, ×tamp, &nonce, body);
let signature = base64_encode(&key.sign(message.as_bytes()));
Ok(SignedHeaders { agent_id: agent_id.to_string(), timestamp, nonce, signature })
}SignedHeaders carries the four values as the headers above.
The panel refuses:
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHENTICATED | A header is missing or malformed, the signature does not verify, or the nonce was already used (each is accepted once, for 15 minutes). |
| 401 | CLOCK_SKEW | The timestamp is more than 5 minutes from the panel's clock: check the server's time. |
| 401 | AGENT_REVOKED | The agent is not registered, was revoked, or its server was removed. |
Download the agent
/api/v1/agent/install.sh/api/v1/agent/package-rs/:arch/api/v1/agent/panel-cert.pemPublic, and limited to 60 downloads a minute per address. install.sh is the agent installer the Add server command runs. package-rs/x64 and package-rs/arm64 are the agent itself, one program for each CPU type, with its version in X-Agent-Version and its SHA-256 in X-Content-SHA256 so agent updates can check it (404 AGENT_PACKAGE_MISSING when the panel has no program for that CPU type). panel-cert.pem is the certificate the panel serves HTTPS with, with its public key pin in X-Panel-Pin (404 NO_PANEL_CERTIFICATE when the panel has no certificate of its own).
Register an agent
/api/v1/agent/registerExchanges a one-time enrollment token for an agent id. Limited to 30 attempts an hour per address. Registering again for the same server replaces, and revokes, its previous agent.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
enrollmentToken | string | Yes | The token from the install command (vpe_…). |
publicKey | string | Yes | The agent's Ed25519 public key, PEM encoded. |
agentVersion | string | Yes | The agent's version. |
system | object | Yes | hostname, and optionally os, kernel, architecture, cpuCores, memoryTotalBytes, diskTotalBytes, uptimeSeconds and timezone. |
Response 201 Created
{
"success": true,
"data": {
"agentId": "6f7a8b9c-…",
"serverId": "9b2e7c1a-…",
"panelPublicKey": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----\n",
"heartbeatIntervalSeconds": 15
},
"message": "Agent registered",
"requestId": "…"
}Errors
| Status | Code | When |
|---|---|---|
| 401 | INVALID_ENROLLMENT_TOKEN | The token is invalid, expired or already used. Every failure is recorded in the audit log. |
| 403 | INSECURE_TRANSPORT | Not over HTTPS. |
| 422 | VALIDATION_ERROR | publicKey is not a PEM Ed25519 key, or another invalid field. |
Send a heartbeat
/api/v1/agent/heartbeatSent every 15 seconds. It marks the server online and carries what the panel shows about it. Only agentVersion and system are required; the rest came with later agent versions and every few minutes.
| Field | What it reports |
|---|---|
agentVersion, system | As in registration. |
metrics | CPU, load, memory, swap, disk, network rates, process count and uptime. |
services, filesystems | Watched systemd services and mounted filesystems. |
operations | The operations this agent can run, so the panel offers only those. |
webStack | Installed software: NGINX, Certbot, PHP versions, Node.js, Python, PM2, MariaDB, BIND, the mail server, phpMyAdmin and more. |
certificates, addresses | Certificates on the server, and its IP addresses. |
applications, databases | App process states and database sizes. |
backups, diskUsage | Backup files present, and folder sizes. |
security, selfCheck, docker | The security summary, the self-check and Docker's state. |
Response 200 OK
{
"success": true,
"data": { "heartbeatIntervalSeconds": 15, "panel": { "url": "https://panel.example.com", "serverName": "web-1" } },
"message": "OK",
"requestId": "…"
}Wait for the next job
/api/v1/agent/jobs/nextA long poll: the panel holds the request for up to 20 seconds, answering as soon as a job is ready for this server, or with 204 No Content when none came. Proxies in front of the panel must allow at least a 60-second read timeout.
Response 200 OK with a signed envelope:
{
"success": true,
"data": {
"envelope": {
"version": 1,
"jobId": "e1f2a3b4-…",
"operationId": "e1f2a3b4-…:1",
"serverId": "9b2e7c1a-…",
"type": "SERVICE_RESTART",
"params": { "service": "nginx" },
"requestedBy": { "type": "user", "id": "3c4d5e6f-…" },
"attempt": 1,
"timeoutSeconds": 120,
"issuedAt": "2026-11-10T14:00:00.000Z",
"expiresAt": "2026-11-10T14:02:00.000Z"
},
"signature": "…"
},
"message": "OK",
"requestId": "…"
}signature is the base64 Ed25519 signature, with the panel's job-signing key, of the envelope as canonical JSON (keys sorted at every level, no spaces). An envelope is valid for 120 seconds. The agent verifies the signature with the key it pinned at registration, that serverId is its own, that it has not expired and that its operationId has not run before.
Report a job started
/api/v1/agent/jobs/:id/startMoves a dispatched job to running. No body. Response 200 OK with data: null.
Errors: 404 NOT_FOUND for a job of another server, 409 INVALID_JOB_STATE when it is not dispatched (details.status).
Send job logs
/api/v1/agent/jobs/:id/logsAppends output lines to a dispatched or running job, shown live in the panel.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
lines | object[] | Yes | 1 to 200 { stream, message }: stream is stdout or stderr, message up to 8000 characters. |
Response 200 OK: { accepted }. A job keeps up to 5000 lines; past that, lines are dropped and a note is added.
Errors: 404 NOT_FOUND, 409 INVALID_JOB_STATE.
Report a job's result
/api/v1/agent/jobs/:id/resultFinishes a job. The service that owns the job's record (a website, an app, a backup…) applies the result before the agent's next poll is answered, so a follow-up job always sees the result of the one before.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Yes | succeeded or failed. |
output | any | No | The operation's result. Output over 256 KB is dropped and replaced by a note. |
error | object | No | { code, message } for a failure. |
Response 200 OK, message Result recorded.
Errors: 404 NOT_FOUND, 409 INVALID_JOB_STATE.
Transfer files
/api/v1/agent/backups/:id/chunks/api/v1/agent/uploads/:id/chunks/:offset/api/v1/agent/downloads/:id/chunksFiles move between a server and the panel in base64 pieces of up to 2 MiB, only while the job that moves them runs:
- Backups for download. While an
UPLOAD_BACKUPjob runs, the agent posts the backup as{ offset, data, final }; the panel answers{ received, final }. Pieces must arrive in order (409 OFFSET_MISMATCHwithdetails.expected), and no more data than the backup holds is accepted. - Uploads from the file manager. While a
FILE_UPLOADjob runs, the agent fetches the uploaded file from the panel piece by piece; the panel answers{ offset, data }(416 OFFSET_OUT_OF_RANGEpast the end). - Downloads from the file manager. While a
FILE_DOWNLOADjob runs, the agent posts the file as{ offset, data, final }; the panel answers{ received }.
Outside their job, these answer 409 NO_UPLOAD or 409 NO_DOWNLOAD.
Report cron runs
/api/v1/agent/cron-runsCron jobs are run by the server's own cron daemon, so they keep running while the panel is down. The agent reports the runs with this request: up to 100 at a time, each { runKey, cronId, trigger, status, exitCode, startedAt, finishedAt, durationMs, output }. A run already recorded (same runKey) is skipped, so reporting again is safe. See Cron jobs.
Response 200 OK: { stored }, the number of new runs recorded.