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
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.