Connect a Server
Enroll an Ubuntu or Debian host with a one-line agent install.
A server joins VPSPilot by running the agent installer with a single-use enrollment token. The agent then reports in every few seconds, and the server shows as online in the dashboard.
Requirements
- Ubuntu (22.04 or later) or Debian (12 or later), on x86_64 or arm64.
- Root access, through
sudo. - Outbound HTTPS to the control plane URL. No inbound port is opened for VPSPilot.
- Docker for container and Compose apps, managed databases and domains. Native (systemd) apps, monitoring, logs and service control work without it.
Install the agent
Create an enrollment
In the dashboard, go to Servers → Enroll a server, name the server (lowercase letters, digits and dashes) and add optional tags. VPSPilot creates an ept_ token valid for 15 minutes and shows the install command.
Run the installer on the server
curl -fsSL https://pilot.example.com/agent/install.sh | sudo bash -s -- --token ept_...The installer is a short, readable script; you can download and read it first. It refuses to run on anything other than Ubuntu or Debian.
Watch it come online
The server moves from pending to online within a few seconds. Host facts, metrics and the service and container inventory start filling in.
What the installer does
- Installs
python3,python3-psutil,gitandcurlfrom apt. - Creates a system user
vpspilotwith no login shell. - Downloads the agent package from the control plane into
/opt/vpspilot-agent. - Redeems the token for a long-lived
agt_agent credential, stored in/etc/vpspilot/agent.jsonwith mode 0600. - Installs and starts two systemd services:
vpspilot-agentandvpspilot-helper.
What gets started
What gets stored
Security check and firewall
Run security check on the server's page reviews SSH login settings (password and root login), the firewall, databases and container ports open to the internet, automatic security updates and pending reboots, and shows how to fix each. From there you can turn on the firewall (SSH, 80 and 443 are allowed first, so you can't lock yourself out), open or close ports (optionally only from one address), and turn on automatic security updates. SSH settings are explained rather than changed, so a missing key can't lock you out. Docker-published ports skip the firewall: use an app's Private port setting for those.
Disk usage
Check disk usage shows where the space went (images, build cache, volumes, backups, releases, logs, apt cache) and what can go. Clean up removes only the build cache, untagged images, system logs over 200 MB and the apt cache: never containers, volumes or the images kept for rollbacks.
System updates
The server's page lists pending package updates (security ones first) and whether a reboot is needed, with buttons to install security updates, all updates, or reboot. apt runs in its own systemd unit, so it finishes even if VPSPilot restarts mid-way. An update to Docker restarts every container for a few seconds. See Security updates pending for the alert.
Upgrade the agent
Run the installer again without a token. It replaces the code in place and restarts both services; the enrollment is kept.
curl -fsSL https://pilot.example.com/agent/install.sh | sudo bashRemove a server
Revoke invalidates the agent credential immediately; the agent exits and systemd does not restart it. To clean up the host afterwards:
sudo systemctl disable --now vpspilot-agent vpspilot-helpersudo rm -rf /opt/vpspilot-agent /etc/vpspilot /etc/systemd/system/vpspilot-*.servicesudo systemctl daemon-reloadRemoving the agent leaves your containers, databases and backups in place. Delete them from the dashboard first if you want them gone.