Connect a fleet agent
A fleet agent is a small daemon you run on another VPS so Dockstash can back up the containers on that host too. The agent phones home over HTTPS — no inbound ports are opened on your machine — and runs the same dump-then-restic pipeline as the primary server. Fleets are available on every plan — Free connects 1 server, Pro 5, and Business unlimited.
How to do it
Open the Fleet screen
In the dashboard go to Fleet. This screen lists every registered agent with its online/offline status, version, and last heartbeat.
Register the agent
Click Register agent and give it a name and the host it will run on. In the same dialog, set the Project directories field to where your Compose projects live on that VPS (default /var/www) — the agent will only ever discover, back up, and restore inside those directories.
Copy the one-time token
Registration mints a token shaped dsa_<agentId>.<secret> and shows it exactly once — it is stored only as a keyed HMAC on the server and can never be retrieved again. Copy it now. If you ever lose it, use Rotate key on the agent’s row; the old token stops working the moment a new one is minted.
Install the agent on the VPS
The register dialog shows a copy-paste docker-compose block, pre-filled with your token and project directories. Paste it on the target VPS and bring it up. The bundled docker-socket-proxy grants the agent least-privilege access to Docker (containers + exec only) — it never touches the raw socket.
docker compose -f docker-compose.agent.yml pull docker compose -f docker-compose.agent.yml up -d --force-recreateCheck the project directories are mounted
Every directory you listed must also be bind-mounted read-write in the compose file (same path inside and outside the container) — restores write files back. To add a directory later, open the agent’s Setup dialog, add it, and re-run the printed compose command.
Verify the agent is online
Within about 30 seconds the agent’s first heartbeat lands and the Fleet row flips to online. If it stays offline, check that both containers are up and that your Dockstash URL is reachable from the VPS.
docker compose -f docker-compose.agent.yml psAssign a project to the agent
Open a project’s Plan tab and set "Runs on" to the new agent (the default is "This server (local)"). From then on, scheduled and on-demand backups for that project are claimed and executed by the agent, streaming live logs back to your dashboard.
Do it in one click with Dockstash
Dockstash runs the exact dump above, restics it off-site, and drill-tests the restore automatically — no script to maintain.
Last updated: July 2026
Related guides
Schedule automatic backups
Set a daily backup, a weekly prune with retention, integrity checks, and restore drills — validated cron, one job per repository, live logs.
Troubleshoot failing backups
Read live restic logs, let stale locks fix themselves, revive offline agents, and understand heartbeat alerts.
PostgreSQL
Back up PostgreSQL in Docker
MySQL
Back up MySQL in Docker
Frequently asked questions
Does the Dockstash server connect into my VPS?
No. Connectivity is outbound-only: the agent polls and heartbeats over HTTPS with a Bearer token. You never open an inbound port, and the server never dials your machine.
What can the agent see on my server?
Only what you allow. Filesystem access is limited to the project directories you configured (and they must be explicitly bind-mounted), and Docker access goes through a socket proxy that exposes only container listing and exec — no image builds, no volume mounts, no host root.
What happens if the agent dies mid-backup?
Every job has a lease (default 15 minutes, renewed while logs stream). If the lease expires the job is marked failed and an alert is sent — it is never silently retried, so you always know a run did not finish.
Do restore drills run on fleet agents?
Not yet — drills still run on the primary server. Backup, verify (restic check), prune, and restore all run remotely on the agent.
I rotated the key and now the agent gets 401s. What do I do?
The running container still holds the old token. Update DOCKSTASH_AGENT_TOKEN in docker-compose.agent.yml and recreate the container. Rotation invalidates the old token immediately by design.