Core concepts

Security Model

What runs as root, how secrets are stored, and what VPSPilot will refuse to do.

VPSPilot holds the keys to your servers, so it is designed so that a compromise of any one part gives as little as possible. This page describes what each part can do and how secrets are handled.

Network exposure

Agents connect out over HTTPS. Nothing listens on your servers for VPSPilot.
The API only needs to be reachable by browsers (through the dashboard) and by agents.
The helper’s Unix socket is local and restricted to the vpspilot group.

Least privilege on the server

Component	Privileges
Agent	Unprivileged user, NoNewPrivileges, ProtectSystem=strict, read-only home, write access only to /var/lib/vpspilot and /etc/vpspilot.
Helper	Root, but only a fixed set of operations with validated arguments. No shell, no arbitrary commands. Job secrets never reach its log.
Native (systemd) apps	Each app runs, and builds, as its own system user in a hardened unit: read-only system, private /tmp, no new privileges, no capabilities.
Compose apps	Privileged mode, host namespaces, devices, binds outside the repository, the Docker socket and external volumes are refused.
Repository content	Treated as untrusted. Files are read with size limits; anything copied into a generated Dockerfile must match strict patterns.

Credentials and tokens

Credential	Lifetime	Stored as
`ept_…`	Single use, 15 minutes	Hash
`agt_…`	Until revoked	Hash on the control plane, 0600 file on the server
Access token	15 minutes	Memory only in the browser
Refresh token	30 days, rotates on use	Hash; httpOnly SameSite=Lax cookie scoped to /api/v1/auth
Recovery codes	Single use	Hash
GitHub repo token	One deployment	Not stored; minted per deploy, read-only, single repository
Google Drive	Refresh token until disconnected	Encrypted; backup jobs get an access token valid about an hour

Secrets at rest

Environment variables, database passwords, authenticator secrets, GitHub App keys, storage keys and Google tokens, alert channel destinations, backup keys and job output are encrypted with ENCRYPTION_KEY before they reach the database. Database exports and imports in transit are encrypted with AES-GCM and deleted within a day. Secret values are write-only in the dashboard: once saved, they are never sent back to the browser.

Rotating the encryption key

bash

# 1. Generate a new keyuv run python -m app.encryption generate-key# 2. Set ENCRYPTION_KEY to the new key and move the old one#    into ENCRYPTION_KEYS_PREVIOUS, then restart the API# 3. Re-encrypt every stored secret with the new keyuv run python -m app.encryption rotate

On a self-hosted install, edit /opt/vpspilot/api/deploy/.env, run sudo vpspilot restart, then sudo docker exec vpspilot-api python -m app.encryption rotate. Download a new recovery kit afterwards.

Backups

Each backup is encrypted with AES-256 on the server before it is written to disk or uploaded. The key is held by the control plane, encrypted at rest, and handed to the agent only for the job that needs it. A copy of your bucket alone can’t be read, so keep the recovery kit offline: without it, neither can you if the control plane is lost.

Audit trail

Every change, from deployments and database actions to domain edits, server revocations and settings changes, is written to the audit log with who did it, from which IP, and when. See Notifications and Audit.