Install VPSPilot
Install the dashboard, API and database on your server with one command, behind HTTPS.
The control plane is the dashboard, the API and a PostgreSQL database for VPSPilot's own state. One command installs all of it on an Ubuntu or Debian server, behind HTTPS on a domain of your choice. It can be a small VPS of its own or one of the servers you want to manage: the same machine can run the control plane and your apps.
Requirements
- Ubuntu 22.04 or later, or Debian 12 or later, on x86_64 or arm64, with root access.
- 2 GB of memory (building the dashboard needs it) and about 20 GB of disk.
- Ports 80 and 443 free. VPSPilot's proxy (Caddy) answers on them for the dashboard and, later, your apps' domains. If nginx or Apache already serves sites there, see below.
- A domain name for the dashboard, such as
pilot.example.com. - Optional: a Resend API key for email. Without one, sign-in codes are written to the API log.
Install
Point the domain at the server
Add an A record for the dashboard's hostname with the server's public IP (and an AAAA record if it has IPv6). On Cloudflare, leave the record as DNS only so the certificate can be issued. Wait until it resolves:
dig +short pilot.example.comRun the installer
curl -fsSL https://raw.githubusercontent.com/philtechphilips/VPS-PIlot-BE/main/deploy/install.sh \ | sudo bash -s -- --domain pilot.example.com --email you@example.comIt takes five to ten minutes the first time. Add --resend-key re_… to send email. Running it again later is safe: it keeps the existing keys and data.
Create the owner account right away
Open https://pilot.example.com/setup. Whoever opens it first becomes the owner, so do this before sharing the address. Continue with First-run Setup.
Installer options
What the installer does
- Installs Docker, if it isn't there yet.
- Clones the API and the dashboard into
/opt/vpspilot/apiand/opt/vpspilot/web. - Generates the database password,
SECRET_KEYandENCRYPTION_KEYinto/opt/vpspilot/api/deploy/.env(mode 0600). - Builds and starts the containers below. Database migrations run every time the API starts.
- Starts the proxy and obtains a certificate for your domain.
- Installs the
vpspilotcommand.
The proxy is the same one the agent manages for your apps' domains, so the control plane and your apps share ports 80 and 443 on one server. The dashboard's own site lives in /var/lib/vpspilot-proxy/extra/control-plane.caddy; the agent never rewrites it.
After installing
- Manage this server too: in Servers → Enroll Server, run the command it shows on the same server. See Connect a Server.
- Download the recovery kit from Settings → Security and keep it offline. It holds the keys that decrypt your stored secrets and backups.
- Add off-server backup storage (Cloudflare R2, S3, Google Drive…) in Settings → Backup Storage. See Off-server Storage.
Manage the control plane
Settings live in /opt/vpspilot/api/deploy/.env; every variable is listed in Configuration.
nginx or Apache already running
Only one program can own ports 80 and 443. Check what the existing web server serves before stopping it:
sudo nginx -T 2>/dev/null | grep -E "server_name|proxy_pass|root "sudo apache2ctl -S- If it only serves the default page, stop it with
sudo systemctl disable --now nginx apache2and run the installer. - If it serves real sites, move each one into VPSPilot as an application with a domain, then retire the old server. Until then you can move the old server to another port (say 8080) and route its domain through VPSPilot's proxy with a file in
/var/lib/vpspilot-proxy/extra/.
PostgreSQL, MySQL or Redis already on the server keep running untouched; connect them in Databases → Connect an existing one (host 127.0.0.1). See Database Overview.
Manual install (advanced)
For development, or a server that will never host apps' domains, you can run the pieces yourself: Python 3.12 with uv for the API, Node.js 20.9+ for the dashboard, and PostgreSQL 14+.
# APIcd be && uv sync && cp .env.example .env # fill in the database, SECRET_KEY, ENCRYPTION_KEYuv run poe migrateuv run uvicorn app.main:app --host 127.0.0.1 --port 8000# Dashboard (proxies /api/* to the API)cd frontend && npm ciAPI_URL=http://127.0.0.1:8000 npm run buildnpm run start -- -p 3000When you add a domain to an app, the agent starts VPSPilot's proxy on ports 80 and 443. A separate Caddy or nginx there makes that fail. Either use the installer, or put the dashboard's site in /var/lib/vpspilot-proxy/extra/ and let VPSPilot's proxy serve it. Expose /agent/* on the same hostname so agents can reach the API, and keep port 8000 bound to localhost.