Using the Agent for private infrastructure

The Agent is for infrastructure VPS Snaps has no inbound path to — behind a NAT gateway, a VPN, or deep inside a private VPC with no public IP. Instead of us connecting to the server, a small program you run on it connects out to us, authenticates, and waits for instructions. No inbound firewall rules, ever.

Step 1 — Register an agent

Go to Agents → Add and give it a name. You'll be shown a Docker command containing a one-time token — copy it now, it isn't shown again.

Step 2 — Run it on the private machine

Run the copied command on the server you want to back up. It needs outbound HTTPS access to vpssnaps.com — nothing else.

docker run -d --name vpssnaps-agent --restart unless-stopped \
  -e VPSSNAPS_AGENT_TOKEN="agt_..." \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/brokehold/vpssnaps-agent:latest

Step 3 — Use it in a backup job

When creating a Database, Docker, or File backup job, you'll see a toggle between "Server (SSH)" and "Agent" next to the connection picker. Choose Agent and select the one you registered — everything else about the job (schedule, retention, storage destination) works exactly the same as an SSH-based job. The agent's image carries pg_dump, mysqldump and — from agent 1.2.6 — mongodump and mongorestore, so nothing needs installing on the machine for a database job.

Where the data goes

The agent uploads directly from the private machine to your own S3-compatible storage destination — the backup data never passes through VPS Snaps' servers while it is taken. We only see job status and logs. ("Verify now" asks your storage whether it is unchanged, without downloading it.)

Restoring onto the agent's machine

Open a successful run of an agent job and choose Restore onto the agent, typing its name to confirm (agent 1.2.5 or later). The agent first backs up what is there now, then downloads the archive, checks it against the checksum recorded when it was taken, and writes it back: files to their paths, each compared with the backup afterwards; Docker volumes emptied and refilled, once the containers using them are stopped; the database replaced. If it fails partway, the backup it took first is put back. A file job reads and writes what is mounted into the agent's container, so mount each path from the host at the same path — without :ro to restore into it. The agent refuses rather than write inside its own container, where a restore would vanish when it restarts.

docker run -d --name vpssnaps-agent --restart unless-stopped \
  -e VPSSNAPS_AGENT_TOKEN="agt_..." \
  -v /var/www:/var/www \
  ghcr.io/brokehold/vpssnaps-agent:latest

If the agent goes offline

It reconnects automatically with a growing backoff. A scheduled backup that fires while the agent is disconnected retries twice over about fifteen seconds before being marked failed with a clear "Agent is not connected" message — check that the container is still running.