Architecture
The control plane, the agent and the privileged helper, and how they talk.
VPSPilot is split into a central control plane that holds the desired state and an agent on every server that carries it out. They are deliberately asymmetric: the control plane never connects to a server, and a server can only ask for work it is allowed to do.
Control plane
A FastAPI application backed by PostgreSQL. It owns users and sessions, servers and their metrics, applications and deployments, databases, domains, alert rules, backups and the audit log. It also runs a background loop, inside the API process, that evaluates alert rules every 30 seconds and starts scheduled backups.
The Next.js dashboard is a client of the same API. It proxies /api/* to the API, so everything the dashboard does is also available to scripts. See API Access.
Agent
A small Python program, standard library plus psutil, that runs as the unprivileged vpspilot user. On its own schedule it:
If the control plane is unreachable, the agent backs off and buffers up to 120 metric samples (about 30 minutes) to send when it reconnects. A server with no heartbeat for 35 seconds is shown as offline.
Privileged helper
Some work needs root: restarting a service, running Docker, reading the journal. That is the job of vpspilot-helper, the only part of VPSPilot that runs as root. It listens on /run/vpspilot/helper.sock, readable only by the vpspilot group, checks the caller’s credentials on every connection, and performs exactly one operation from a fixed list per request.
The helper has no “run this command” operation. Every operation builds an argument list in code from validated inputs; nothing goes through a shell.
How a change reaches a server
- You act in the dashboard, for example by deploying an app. The API validates the request and records a job for that server.
- Within a few seconds the server’s agent claims the job.
- The agent checks the job type and payload again and passes it to the helper.
- The helper validates the arguments a third time and runs the operation, streaming progress events back.
- The agent reports the outcome. The control plane updates the deployment, database or domain and notifies you.
Secrets a job needs, such as environment variables or database passwords, are not stored in the job. The agent fetches them through a separate channel just before running it. See Jobs and Operations.
Docker on the server
Applications, managed databases and the reverse proxy are all Docker containers on a private bridge network called vpspilot. Containers reach each other by name:
Containers whose names start with vpspilot- can't be stopped from the dashboard, so you can't cut yourself off. Native (systemd) apps run outside Docker as vp-<app>.service.