API Reference

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.

Last updated

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.

MethodPathDescription
GET/api/v1/agent/install.shThe install script
GET/api/v1/agent/package-rs/:archThe agent program
GET/api/v1/agent/panel-cert.pemThe panel's certificate
POST/api/v1/agent/registerRegister an agent
POST/api/v1/agent/heartbeatSend a heartbeat
GET/api/v1/agent/jobs/nextWait for the next job
POST/api/v1/agent/jobs/:id/startReport a job started
POST/api/v1/agent/jobs/:id/logsSend job logs
POST/api/v1/agent/jobs/:id/resultReport a job's result
POST/api/v1/agent/backups/:id/chunksSend a backup for download
GET/api/v1/agent/uploads/:id/chunks/:offsetFetch an uploaded file
POST/api/v1/agent/downloads/:id/chunksSend a file for download
POST/api/v1/agent/cron-runsReport cron runs

How the agent is trusted

  1. 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.
  2. 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.
  3. 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.
  4. The agent connects out to the panel; servers need no inbound port. It sends a heartbeat every 15 seconds and long-polls for jobs.
  5. 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:

HeaderValue
X-VaultPanel-Agent-IdThe agent id from registration (a UUID).
X-VaultPanel-TimestampThe time in milliseconds since the Unix epoch.
X-VaultPanel-Nonce16 to 64 random URL-safe characters, never reused.
X-VaultPanel-SignatureThe 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:

agent/src/signing.rs
/// 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, &timestamp, &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:

StatusCodeWhen
401UNAUTHENTICATEDA header is missing or malformed, the signature does not verify, or the nonce was already used (each is accepted once, for 15 minutes).
401CLOCK_SKEWThe timestamp is more than 5 minutes from the panel's clock: check the server's time.
401AGENT_REVOKEDThe agent is not registered, was revoked, or its server was removed.

Download the agent

GET/api/v1/agent/install.sh
Auth
None
GET/api/v1/agent/package-rs/:arch
Auth
None
GET/api/v1/agent/panel-cert.pem
Auth
None

Public, 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

POST/api/v1/agent/register
Auth
Enrollment token in the body

Exchanges 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

FieldTypeRequiredDescription
enrollmentTokenstringYesThe token from the install command (vpe_…).
publicKeystringYesThe agent's Ed25519 public key, PEM encoded.
agentVersionstringYesThe agent's version.
systemobjectYeshostname, 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

StatusCodeWhen
401INVALID_ENROLLMENT_TOKENThe token is invalid, expired or already used. Every failure is recorded in the audit log.
403INSECURE_TRANSPORTNot over HTTPS.
422VALIDATION_ERRORpublicKey is not a PEM Ed25519 key, or another invalid field.

Send a heartbeat

POST/api/v1/agent/heartbeat
Auth
Agent signature (Ed25519)

Sent 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.

FieldWhat it reports
agentVersion, systemAs in registration.
metricsCPU, load, memory, swap, disk, network rates, process count and uptime.
services, filesystemsWatched systemd services and mounted filesystems.
operationsThe operations this agent can run, so the panel offers only those.
webStackInstalled software: NGINX, Certbot, PHP versions, Node.js, Python, PM2, MariaDB, BIND, the mail server, phpMyAdmin and more.
certificates, addressesCertificates on the server, and its IP addresses.
applications, databasesApp process states and database sizes.
backups, diskUsageBackup files present, and folder sizes.
security, selfCheck, dockerThe 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

GET/api/v1/agent/jobs/next
Auth
Agent signature (Ed25519)

A 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

POST/api/v1/agent/jobs/:id/start
Auth
Agent signature (Ed25519)

Moves 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

POST/api/v1/agent/jobs/:id/logs
Auth
Agent signature (Ed25519)

Appends output lines to a dispatched or running job, shown live in the panel.

Request body

FieldTypeRequiredDescription
linesobject[]Yes1 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

POST/api/v1/agent/jobs/:id/result
Auth
Agent signature (Ed25519)

Finishes 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

FieldTypeRequiredDescription
statusstringYessucceeded or failed.
outputanyNoThe operation's result. Output over 256 KB is dropped and replaced by a note.
errorobjectNo{ code, message } for a failure.

Response 200 OK, message Result recorded.

Errors: 404 NOT_FOUND, 409 INVALID_JOB_STATE.

Transfer files

POST/api/v1/agent/backups/:id/chunks
Auth
Agent signature (Ed25519)
GET/api/v1/agent/uploads/:id/chunks/:offset
Auth
Agent signature (Ed25519)
POST/api/v1/agent/downloads/:id/chunks
Auth
Agent signature (Ed25519)

Files 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_BACKUP job runs, the agent posts the backup as { offset, data, final }; the panel answers { received, final }. Pieces must arrive in order (409 OFFSET_MISMATCH with details.expected), and no more data than the backup holds is accepted.
  • Uploads from the file manager. While a FILE_UPLOAD job runs, the agent fetches the uploaded file from the panel piece by piece; the panel answers { offset, data } (416 OFFSET_OUT_OF_RANGE past the end).
  • Downloads from the file manager. While a FILE_DOWNLOAD job 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

POST/api/v1/agent/cron-runs
Auth
Agent signature (Ed25519)

Cron 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.