Server agent
How the VaultPanel agent works on each server — install paths, the root helper, signed jobs, its local policy in config.json, upgrades and its limits.
The agent runs on each managed server as the vaultpanel-agent systemd service. It is one static program written in Rust, built for x86-64 and arm64, so the server needs nothing else installed for it: no Node.js. It reports the server's state to the panel and runs the operations the panel signs, from a fixed allow-list, without a shell.
To connect a server, see Connecting servers. This page is about how the agent works.
Files and services
| Path | What it is |
|---|---|
/usr/local/bin/vaultpanel-agent | The agent's program (agentBinary). Everyone can read and run it: the file manager's worker is the same program, run as each site's user. |
/usr/local/bin/vaultpanel-agent.previous | The program before the last update from the panel. |
/etc/vaultpanel-agent/config.json | Identity and local policy. Mode 600, then root:vaultpanel-agent mode 640 once the agent runs as its own user. |
/etc/vaultpanel-agent/agent.key | The agent's Ed25519 private key. Mode 600, owned by the agent's user once it runs as that user. |
/etc/vaultpanel-agent/panel-ca.pem | The panel's certificate, when the panel uses its own self-signed one. |
/etc/vaultpanel-agent/ (the rest) | Saved cron jobs (cron/), DNS providers' credentials for wildcard certificates (acme-dns/) and the login message's files. |
/etc/cron.d/vaultpanel | One line for each enabled cron job, running vaultpanel-agent cron-run <id>. |
/usr/local/lib/vaultpanel/acme-dns-hook | Certbot's hook for wildcard certificates; it runs vaultpanel-agent acme-dns-hook. |
/var/lib/vaultpanel | The agent's state: agent-mode.json (the move to its own user), cron results and the ACME challenge folder. |
/var/backups/vaultpanel | Website, app and database backups (backupRoot, root only). |
/var/cache/vaultpanel | Caches: npm, CMS downloads and file manager uploads in progress. |
/var/lib/vaultpanel-ai | The assistant's local model, when installed on the panel's own server. |
vaultpanel-agent register|run|status|version|cron-run <id>|helper|acme-dns-hook|panel-pin|set-panel| Command | What it does |
|---|---|
register | Registers with the panel using an enrollment token (the install script runs it). |
run | Runs the agent (vaultpanel-agent.service). |
status | Prints one telemetry snapshot without contacting the panel. |
version | Prints the version, such as 0.42.0-rs.2. |
cron-run <id> | Runs one cron job; started by cron. |
helper | Runs the root helper (vaultpanel-agent-helper.service). |
acme-dns-hook | Adds and removes Let's Encrypt DNS checks; run by Certbot. |
panel-pin <cert.pem> | Prints a certificate's public key pin; the install script uses it to check the panel's certificate. |
set-panel --panel <url> | Points the agent at a new panel address, keeping its registration. |
What it does
- Heartbeat every 15 seconds: hostname, OS, kernel, architecture, CPU, memory, disk, load, network rates, every real mounted filesystem (up to 20), the state of the services in
watchServices, and the operations this agent version supports. Every few minutes it adds the web stack (NGINX, PHP-FPM versions, Certbot), the panel's certificates, the server's IP addresses, Git, PM2, Python, Node.js and MariaDB versions, the state of each app's process, database sizes, the time zone and the backup files on disk. - Self-check every 5 minutes (agent 0.39.0): what the panel's features need from the server. See Server self-check.
- Disk use of each site folder, measured in the background at most every 15 minutes, for hosting plans' disk limits.
- Jobs: long-polls the panel, runs one job at a time, streams log lines and reports the result.
Operations
The agent runs only operations from its catalog: services, processes and reboots, the web stack and PHP versions, websites, SSL, files, apps and deployments, databases, backups, cron jobs, the firewall, SSH, Fail2ban and updates, DNS, email, containers and the assistant's local model. The full list, with what each one accepts, is in the jobs API reference.
How they run:
- Commands run with a fixed argument list, never through a shell, with a timeout.
- Configuration files are generated by the agent from checked values. Every NGINX, PHP-FPM or Apache change is written next to the old file, tested (
nginx -t,php-fpm -t,apache2ctl configtest) and only then reloaded; if the test fails, the previous files are put back. - App install, build and start commands are split into arguments by the agent; pipes,
;,&&, redirects and$(…)are refused. They run as the app's own Linux user. - SQL goes to the
mysqlclient on stdin, never the command line, so passwords do not show in the process list. - File manager requests run in a separate process as the site's own user, inside its home folder; symbolic links are listed but never followed.
- Containers are created through Docker's Engine API over its socket: unprivileged,
no-new-privileges, named volumes only, ports bound to127.0.0.1unless the panel asks otherwise.
Refusals that protect the server
Whatever the panel asks, the agent refuses what would lock people out or harm the server:
- the firewall always keeps the SSH ports and the panel's ports open (
LOCKOUT_REFUSED); - SSH settings and key removals must leave an administrator account able to sign in;
- a process signal is refused when the pid now belongs to a different command (
PROCESS_CHANGED), is a kernel thread, the agent itself or a protected process (systemd,init,sshd,systemd-journald,systemd-logind,systemd-udevd,dbus-daemon); - the agent's own units can never be stopped or restarted through a job, and
ssh/sshdcan never be stopped; - containers publishing the panel's database or Redis ports, or labelled
io.vaultpanel.protected, can be started but never stopped, restarted or removed (PROTECTED_CONTAINER).
Trust
- The agent signs every request with its private key; the panel stores only the public key.
- The panel signs every job envelope. The agent pinned the panel's key at registration and refuses envelopes that are unsigned, tampered with, addressed to another server, expired or already run.
- Removing a server, or registering a new agent for it, revokes the old agent. A revoked agent stops.
- With the panel's self-signed certificate, the install command carries the certificate's public key pin. The installer checks it, saves the certificate as
panel-ca.pem, and the agent trusts that certificate directly, alongside the system's certificate authorities.
The root helper
From agent 0.36.0, an agent that starts as root under systemd from /usr/local/bin/vaultpanel-agent (agentBinary) moves itself to two services:
| Service | Runs as | Does |
|---|---|---|
vaultpanel-agent | vaultpanel-agent, a system user without a shell or home | Talks to the panel: heartbeat, jobs, terminal link. No capabilities, NoNewPrivileges, read-only system, no /home or /root. |
vaultpanel-agent-helper | root | Runs jobs and opens terminal shells, reads what the heartbeat needs from root-only files. Has no connection to the panel. |
They talk over /run/vaultpanel-agent-helper/helper.sock (mode 660, group vaultpanel-agent), one JSON message per line. The helper does not take the agent's word for anything that changes the server: it checks every job and terminal request itself against the panel's key in the root-owned config.json (signature, server, expiry, not seen before). The agent's user can read config.json but not change it.
If the agent does not reach the panel as its own user within 10 minutes, the helper puts the single root service back (the original unit is kept as vaultpanel-agent.service.root) and the server's security checks say why ("Agent privileges"). It does not try again until /var/lib/vaultpanel/agent-mode.json is removed and the agent restarted. Set "runAsRoot": true in config.json to keep one root service.
Local policy
/etc/vaultpanel-agent/config.json holds the agent's identity and a local policy. The server owner's policy wins over anything the panel asks. Edit the file as root, then restart vaultpanel-agent, and vaultpanel-agent-helper too when the agent runs as its own user (the helper enforces the policy for jobs). Keys you leave out take their defaults.
Allow and refuse
| Key | Default | Set to false to refuse |
|---|---|---|
allowReboot | true | Reboots. |
allowProcessSignals | true | Stopping or killing processes. |
allowWebsites | true | Every website, SSL and file operation. |
allowWebStackInstall | true | Installing packages. |
allowApplications | true | Every app operation. |
allowDatabases | true | Every database operation. |
allowBackups | true | Every backup and restore. |
allowCron | true | Every cron job operation. |
allowFirewall, allowSshConfig, allowFail2ban, allowUpdates | true | Firewall, SSH (and login message), Fail2ban or update changes. |
allowSelfUpdate | true | Updates from the panel (use the upgrade command instead). |
allowContainers | true | Every Docker and container operation. |
allowTerminal | true | The server terminal; the panel then says it is turned off. |
allowDns | true | Every DNS operation. |
allowMail | true | Every email operation. |
Services
| Key | Default | Meaning |
|---|---|---|
allowedServices | nginx, apache2, php*-fpm, mariadb, mysql, postgresql, redis, docker, cron, ssh, ufw, fail2ban, pm2-* and others | Units that may be restarted or inspected (globs). |
watchServices | Common web stack units | Units reported in the heartbeat. |
Paths and layout
| Key | Default | Meaning |
|---|---|---|
diskPath | / | Filesystem reported as disk usage. |
sitesRoot | /var/www | Where site home folders are created. |
nginxSitesAvailable, nginxSitesEnabled, nginxConfD, nginxLogDir | Debian and Ubuntu paths | NGINX layout. |
acmeWebroot | /var/lib/vaultpanel/acme | Shared folder for Let's Encrypt HTTP challenges. |
letsencryptDir, phpConfRoot, phpRunDir, webServerUser | /etc/letsencrypt, /etc/php, /run/php, www-data | Certbot, PHP-FPM and web server layout. |
systemdUnitDir | /etc/systemd/system | Where the pm2-<app> units are written. |
nodeBinDir | A Node.js in /usr/local/bin or /usr/bin | Node.js used to run apps and PM2. The agent itself does not use Node.js. |
npmCacheDir | /var/cache/vaultpanel/npm | npm's cache when installing PM2. |
mysqlDefaultsFile | none | A MySQL options file with root credentials, when root cannot use the unix socket. |
deployEnv | {} | Extra environment for git, npm and pip during deployments, for example HTTPS_PROXY. |
backupRoot | /var/backups/vaultpanel | Where backups are kept (root only). |
backupMinFreeBytes | 512 MiB | Backups are refused when less than this is free in backupRoot. |
maxExtractBytes | 20 GB | The largest archive the file manager extracts. |
cronFile, cronSpecDir, cronStateDir | /etc/cron.d/vaultpanel, /etc/vaultpanel-agent/cron, /var/lib/vaultpanel/cron | Cron layout. |
agentBinary | /usr/local/bin/vaultpanel-agent | The agent's program. Updates from the panel only run when the agent runs from here. |
dockerSocket | /var/run/docker.sock or /run/docker.sock | Docker's API socket. |
terminalHostNamespace | true | Start terminal shells in the host's mount namespace, outside the service's sandbox. |
runAsRoot | false | Keep one root service instead of its own user plus the root helper. |
bindConfDir | /etc/bind | BIND's configuration folder; zones go in its vaultpanel/ folder. |
acmeDnsDir | /etc/vaultpanel-agent/acme-dns | DNS providers' credentials for wildcard certificates. |
mailRoot | /var/mail/vhosts | Where mailboxes are kept. |
Upgrading
Agents report the operations they support. Operations added after an agent was installed are refused with AGENT_OUTDATED, and the server page shows how to upgrade.
Versions look like 0.42.0-rs.2. The release numbers carry on from the old Node.js agent's 0.42.0, so a version requirement such as "agent 0.38.0 or newer" is met; -rs.N tells the panel that this agent updates with a program for its CPU type.
From the panel (agent 0.7.0 and newer): Update agent on the server page, or a bulk action. The signed job names the version, size and SHA-256 of the program the panel serves for the server's CPU type. The agent downloads it from /api/v1/agent/package-rs/<x64|arm64>, refuses it if anything differs, runs the new program once to check its version, swaps it into /usr/local/bin/vaultpanel-agent and keeps the old one as vaultpanel-agent.previous. The panel offers the update only when it has the program for that server's CPU type. To go back, move .previous into place and restart the service.
Servers still on the old Node.js agent cannot be updated this way: they move once with the upgrade command below. See Moving from the Node.js agent.
From the server, with the command the server page shows:
curl -fsSL https://panel.example.com/api/v1/agent/install.sh \
| sudo bash -s -- --upgrade --panel https://panel.example.com--upgrade replaces the program, keeps /etc/vaultpanel-agent (identity and policy) and restarts the service. On a server with the old Node.js agent it also moves it to the current one and removes /opt/vaultpanel-agent. With a self-signed panel certificate, the command also carries --panel-pin and the pinned curl options. The panel's own server is updated automatically when the panel starts.
Limits
- Website, app, database and security operations target Debian and Ubuntu (apt, UFW,
www-data,/etc/php/<version>/fpm). - Whatever the panel signs runs as root in the helper: a panel that is broken into can still do everything the operations allow. They are allow-listed and checked, and the terminal is for owners only. Use the local policy to turn off what a server should never do.
- The agent runs on 64-bit Linux on x86-64 and arm64 only.
Architecture
How VaultPanel's control plane, background worker and server agents fit together, from an API request through the job queue to a command on a server.
Plugins
Extend VaultPanel with plugins — separate programs that call the API with their own token, receive signed events and add a page to the panel's sidebar.