Reference
Agent CLI
Agent commands, files, services and upgrades.
The agent is a Python package at /opt/vpspilot-agent. You rarely need to run it by hand, but these commands help when diagnosing a server.
Commands
status
Prints the enrollment (control plane URL, server id and name) and the host facts the agent reports.
bash
sudo -u vpspilot env PYTHONPATH=/opt/vpspilot-agent python3 -m vpspilot_agent statusenroll
Redeems an enrollment token and writes the config file. The installer runs this for you.
bash
sudo -u vpspilot env PYTHONPATH=/opt/vpspilot-agent python3 -m vpspilot_agent enroll \ --url https://pilot.example.com --token ept_... --config /etc/vpspilot/agent.jsonrun
The main loop: heartbeats, metrics, inventory and jobs. systemd runs it as the vpspilot-agent service.
Services
The agent exits with status 78 when its credential is revoked, and systemd is configured not to restart it in that case.
Config file
/etc/vpspilot/agent.json (mode 0600)json
{ "api_url": "https://pilot.example.com", "server_id": "c1f04d…", "server_name": "web-1", "agent_token": "agt_…", "heartbeat_seconds": 10, "metrics_seconds": 15}Agent protocol
Agents authenticate with their agt_ token as a bearer token. All calls are outbound from the server.
GET
/agent/install.shThe installer script, with this control plane's URL filled in.
GET
/agent/package.tar.gzThe agent package the installer downloads.
POST
/agent/v1/enrollRedeem an enrollment token for an agent token.
POST
/agent/v1/heartbeatLiveness; the reply carries the agent's configuration.
POST
/agent/v1/metricsA batch of metric samples.
POST
/agent/v1/inventoryServices, containers and listening ports.
POST
/agent/v1/jobs/claimClaim the next queued job, if any.
GET
/agent/v1/jobs/{id}/secretsSecrets for a claimed job.
PUT
/agent/v1/jobs/{id}/artifactUpload a database export (streamed, encrypted on arrival).
GET
/agent/v1/jobs/{id}/artifactDownload the file a database import loads.
POST
/agent/v1/requestsPer-site request counts from the proxy's access log.
POST
/agent/v1/jobs/{id}/eventsProgress events.
POST
/agent/v1/jobs/{id}/completeThe job's result.