# Agent protocol

URL: https://docs.vaultpanel.net/api-reference/agent

> 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](https://docs.vaultpanel.net/developers/agent) and [Connecting servers](https://docs.vaultpanel.net/guides/servers/connecting-servers).

> **Internal API:**
These endpoints authenticate agents only. Session cookies, API tokens and billing keys are not accepted on them, and they may change between releases together with the agent.

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/agent/install.sh` | [The install script](https://docs.vaultpanel.net/api-reference/agent#download-the-agent) |
| GET | `/api/v1/agent/package-rs/:arch` | [The agent program](https://docs.vaultpanel.net/api-reference/agent#download-the-agent) |
| GET | `/api/v1/agent/panel-cert.pem` | [The panel's certificate](https://docs.vaultpanel.net/api-reference/agent#download-the-agent) |
| POST | `/api/v1/agent/register` | [Register an agent](https://docs.vaultpanel.net/api-reference/agent#register-an-agent) |
| POST | `/api/v1/agent/heartbeat` | [Send a heartbeat](https://docs.vaultpanel.net/api-reference/agent#send-a-heartbeat) |
| GET | `/api/v1/agent/jobs/next` | [Wait for the next job](https://docs.vaultpanel.net/api-reference/agent#wait-for-the-next-job) |
| POST | `/api/v1/agent/jobs/:id/start` | [Report a job started](https://docs.vaultpanel.net/api-reference/agent#report-a-job-started) |
| POST | `/api/v1/agent/jobs/:id/logs` | [Send job logs](https://docs.vaultpanel.net/api-reference/agent#send-job-logs) |
| POST | `/api/v1/agent/jobs/:id/result` | [Report a job's result](https://docs.vaultpanel.net/api-reference/agent#report-a-jobs-result) |
| POST | `/api/v1/agent/backups/:id/chunks` | [Send a backup for download](https://docs.vaultpanel.net/api-reference/agent#transfer-files) |
| GET | `/api/v1/agent/uploads/:id/chunks/:offset` | [Fetch an uploaded file](https://docs.vaultpanel.net/api-reference/agent#transfer-files) |
| POST | `/api/v1/agent/downloads/:id/chunks` | [Send a file for download](https://docs.vaultpanel.net/api-reference/agent#transfer-files) |
| POST | `/api/v1/agent/cron-runs` | [Report cron runs](https://docs.vaultpanel.net/api-reference/agent#report-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:

| 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:

```rust
/// 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:

| 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

`GET /api/v1/agent/install.sh` — Auth: public

`GET /api/v1/agent/package-rs/:arch` — Auth: public

`GET /api/v1/agent/panel-cert.pem` — Auth: public

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**

| 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`

```json
{
  "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

`POST /api/v1/agent/heartbeat` — Auth: agent

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.

| 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](https://docs.vaultpanel.net/guides/servers/self-check) and Docker's state. |

**Response** `200 OK`

```json
{
  "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

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:

```json
{
  "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

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

Appends 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

`POST /api/v1/agent/jobs/:id/result` — Auth: agent

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**

| 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

`POST /api/v1/agent/backups/:id/chunks` — Auth: agent

`GET /api/v1/agent/uploads/:id/chunks/:offset` — Auth: agent

`POST /api/v1/agent/downloads/:id/chunks` — Auth: agent

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

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](https://docs.vaultpanel.net/api-reference/cron-jobs#list-runs).

**Response** `200 OK`: `{ stored }`, the number of new runs recorded.
