Agents & Sites

Agents run on each host you protect. They poll the dashboard for jobs (backups, restores, exports). There is no agent inbound HTTP API. AI clients (Claude, Cursor, and similar) talk to the dashboard’s built-in MCP server, not to these workers.

Model: Dashboard = control plane. Agent = poll-only worker with restic on the host.

Add / Upgrade agent

From Agents → Add / Upgrade agent, three paths:

Path	When to use
Upgrade (SSH)	Recommended for existing hosts. Pushes the current package to `/opt/reaver-agent`, keeps `data/agent.json` (same agent id), restarts systemd. Does not create a second fleet entry. Provide a sudo password if the deploy user is not root.
New install (SSH)	First-time hosts. Creates a new pairing and agent id when no agent is present. If `reaver-agent.service` or agent files already exist, deploy auto-switches to Upgrade (keeps identity). Deploy credentials are used once and not stored.
Manual pair	Generate a short pairing code, run the install script on the server (`curl` + PHP CLI + network to the dashboard). Script downloads the package, pairs, installs, and starts the worker.

Prefer Upgrade (SSH) whenever you can keep data/agent.json so history and identity stay intact.

Agent fleet

Cards show online/offline, version, and sites. Stat tiles filter the view (Total, Online, Offline, Needs Attention for offline/stale/failures).

Remove offline purges offline/unregistered agents from the registry — use carefully.

Site inventory

Discovered WordPress sites and custom paths appear with path, owning agent, last backup, and status. Search by name/path/agent; filter by backup success/fail/unknown.

Discovery notes:

Paths are normalized so the same directory is not listed twice.
WordPress sites missing from a full successful scan are marked unreachable (custom paths are not marked stale by discovery) (not hard-deleted — schedules/history remain).
A failed scan does not clear inventory.
Empty successful scans can mark that agent’s sites stale.

Sites show up after install/pair discovery or the agent’s normal scan cycle.

Custom path backup

On Agents, expand Custom path backup (admin, collapsible). Register a web directory on an agent so it is backed up like a site (same schedules, Run, primary repo, and license site quota).

Option	Details
Path	Absolute; under a web root (e.g. `/var/www/…`, `/home/…/public_html/…`). Not `/`, `/root`, or shallow roots like `/var/www` alone.
MySQL / MariaDB	Optional dump via `mysqldump` / `mariadb-dump` on the agent; credentials stored encrypted on the dashboard. Included in the same restic snapshot.
SQLite outside path	Optional absolute file path outside the site tree (files inside the path are already backed up).

Discovery does not mark custom paths unreachable when WordPress scan does not list them. Dashboard cards show a Path badge for custom sites.

Agent environment variables

Runtime settings live in /opt/reaver-agent/data/agent.env (also copied to /opt/reaver-agent/.env). The systemd unit loads that file. After editing, restart the agent:

sudo systemctl restart reaver-agent

Upgrade (SSH) rewrites the standard identity lines but preserves REAVER_LOCAL_BACKUP_DIR when already set. Optional timeout keys you add manually should be re-checked after a full reinstall of agent.env.

Core (written by install)

Variable	Default	Purpose
`REAVER_AGENT_ID`	(from pair)	Agent identity (do not change casually)
`REAVER_SECRET_KEY`	(from pair)	Shared secret with the dashboard
`REAVER_DASHBOARD_URL`	(from pair)	Base URL the agent polls
`REAVER_POLL_INTERVAL`	`10`	Seconds between job polls
`REAVER_HEARTBEAT_INTERVAL`	`300`	Seconds between heartbeats
`REAVER_DISCOVERY_INTERVAL`	`3600`	Seconds between site discovery scans
`REAVER_LOCAL_BACKUP_DIR`	install `backups/`	Root for local restic repos

Installer / one-shot only (not required day-to-day):

Variable	Purpose
`REAVER_FORCE_REENROLL=1`	Force a new agent id on install (not recommended)
`REAVER_NONINTERACTIVE=1`	Non-interactive install
`REAVER_AGENT_DIR`	Install path (default `/opt/reaver-agent`)
`REAVER_PAIRING_CODE`	Pairing code for first install

Destination connect timeouts and retries

When a remote destination is slow or briefly down (for example an SSH host rebooting), the agent applies SSH connect timeouts, per-command process limits, and a few connect retries before failing the job with a clear message (and the usual failed-backup email). Auth / wrong-password failures are not retried as connect errors.

Variable	Default	Purpose
`REAVER_SSH_CONNECT_TIMEOUT`	`30`	OpenSSH `ConnectTimeout` in seconds for SFTP destinations (clamped 5–120). Prevents multi-minute hangs on a dead host.
`REAVER_DEST_CONNECT_TIMEOUT`	`60`	Wall-clock seconds for connect/probe restic commands (`snapshots` and similar). `init` uses at least 90s. Process is killed if exceeded.
`REAVER_DEST_CONNECT_RETRIES`	(unset → 2)	Number of extra retries after the first attempt on connect-like failures. Default effective total: 3 attempts (1 try + 2 retries). Max effective attempts is 5. Backoff is 5s then 15s between tries.
`REAVER_DEST_BACKUP_TIMEOUT`	`14400`	Wall-clock seconds for long `backup` / `restore` restic runs (4 hours). Independent of the short connect/probe limit.

Example — slightly more patient SSH during maintenance windows:

# /opt/reaver-agent/data/agent.env (append; then restart reaver-agent)
REAVER_SSH_CONNECT_TIMEOUT=45
REAVER_DEST_CONNECT_TIMEOUT=90
REAVER_DEST_CONNECT_RETRIES=2

Also see Backup Jobs → Destination timeouts and Offsite → Agent-side timeouts.

Reinstall & disaster recovery

When a host is rebuilt or /opt/reaver-agent is wiped:

Secret	Where it lives	After reinstall
Local restic password	Dashboard (encrypted credentials), same model as remote	Included in Security → Recovery keys. New or re-paired agents unlock local repos via jobs supplied by the dashboard.
Remote restic password	Dashboard (encrypted credentials)	Included in Security → Recovery keys; agents unlock offsite repos via jobs.

Local and remote repository passwords are both dashboard-managed. Agents do not keep a long-lived local-only restic password as the source of truth.

Operator checklist

Prefer Upgrade (SSH) when data/agent.json can be preserved.
Before wiping a host, if possible export archives for critical sites (Restore → Export) and keep a current Security → Recovery keys bundle offline.
On a new host: restore agent identity if needed then Upgrade, or New install / Manual pair (new agent id).
Wait for discovery; set primary repos if needed.
Queue a backup or unlock/restore job — the dashboard supplies restic credentials for local and remote destinations.
If recovery material was lost and client-side encryption was enabled, old repositories may be unrecoverable (same rule for local and remote).

Operator tips

Prefer Upgrade over New install to keep agent id and history.
If a site is missing, refresh Agents and check agent logs / journalctl for reaver-agent on the host.
Stuck “Connecting to remote destination…”: check Offsite credentials and host reachability, then re-queue.
Odd panel layouts (Plesk/cPanel custom paths) may need custom path configuration as the product evolves.