How it works

The VaultPanel control plane, the agent on each server, and the signed jobs that carry every change between them.

Last updated

VaultPanel is split into a control plane (the panel) and a small agent on each server it manages. The panel decides what should happen; the agent does it, using only fixed commands from a catalog both sides agree on.

The parts

Browser ── React UI
              │  HTTPS, session cookie + CSRF token
              ▼
        Express API (as the vaultpanel user) ─── MariaDB (users, servers, jobs, audit log…)
              │                              └── Redis (agent nonces, background queues)
              │  HTTPS, Ed25519-signed requests      ▲
              ▼                                      │
        Agent on each server                 Worker
              │  fixed commands, no shell           maintenance every 15 s
              ▼
        systemd, ps, /proc …
PartWhat it does
Web interfaceThe React app you use in the browser.
APIThe Express API behind the web interface, the CLI, the SDK and plugins. It runs as the unprivileged vaultpanel user.
WorkerBackground work: scheduled backups, webhook deliveries, alert rules, marking silent servers offline, timing out stuck jobs and pruning old data.
MariaDB and RedisThe panel's own database and queue. On an installed panel they run in Docker on 127.0.0.1, separate from any database your websites use.
AgentOne program written in Rust on each server (/usr/local/bin/vaultpanel-agent, for x86-64 or arm64), running as the vaultpanel-agent service. It needs nothing else installed, Node.js included.

The agent connects out

Agents open every connection themselves, so a managed server needs no inbound port for the panel. Every 15 seconds an agent sends a heartbeat with system information, metrics and the state of its services, and it long-polls the panel for work.

Each agent has its own Ed25519 key pair. It signs every request (method, path, timestamp, nonce and a hash of the body), and the panel checks the signature, a five-minute clock window and that the nonce was never used before.

From agent 0.36.0, the agent runs as its own unprivileged user. A separate root helper, vaultpanel-agent-helper, runs the jobs; it has no connection to the panel and checks every job's signature itself.

Every change is a signed job

When you create a website, deploy an app or restart a service, the panel turns it into a job:

  1. The panel checks the operation is in the catalog, that you have the permission for it and that the parameters are valid. It refuses a duplicate of a job that is still running.
  2. When the agent claims the job, the panel sends it in an envelope signed with the panel's key, which the agent pinned when it registered.
  3. The agent verifies the signature, that the job is addressed to its server and has not expired, and validates the parameters again against its own allow-list.
  4. It runs fixed commands without a shell, streams the log back and reports the result.

There is no endpoint that runs arbitrary commands, on the panel or on the agent. The one exception by design is the browser terminal, which only owners can open.

Jobs are stored in the panel's database, so you can follow each one live and read its log afterwards under Monitoring > Jobs. Passwords, environment values and file contents in a job's parameters are redacted once the job ends.

The panel's own server

The server the panel is installed on connects itself. Before the API starts, a short step running as root adds the server to the panel (marked This server), writes the agent's identity and installs or updates the agent. You never run an install command for it, and its agent is updated automatically when the panel is.

Learn more