Agents
An agent is the vecta-agent process installed on one Linux server; it pulls that server's jobs and runs restic locally.
Requirements
- Linux x86_64.
- Root access.
flockfrom util-linux.- Outbound HTTPS access to
vectaapp.com. - restic, supplied by the recommended installer or installed separately for a manual setup.
For PostgreSQL backups, install pg_dump 9.0 or newer and Restic 0.17.0 or newer with stdin-command and stdin-filename support on the agent. The database server can be remote if the agent can reach it. Install pg_restore on the machine where you will restore.
One server normally runs one agent. Register another agent for each additional machine.
Installing and registering
In the dashboard, open Agents, start a new registration, and name the server. The registration token is single-use and valid for 24 hours.
The recommended installer downloads and verifies restic and the agent, registers it, writes configuration, installs a cron schedule, and runs once:
curl -fsSL https://vectaapp.com/install.sh | sudo bash -s -- --token <TOKEN>
Replace <TOKEN> with the token from the dashboard.
For a manual installation where restic and the agent are already present:
sudo vecta-agent register --token <TOKEN>
sudo vecta-agent run
Registration exchanges the one-time dashboard token for the agent's credentials. On success, the
CLI prints the registered agent name (or its ID when no name is returned) and the path of the
configuration file it wrote. The file is /root/.config/vecta/config.toml when you run the agent
as root, and contains the agent ID, the API key, and the optional agent name. It is created with
mode 600. The API key is saved in that file and is not shown in the dashboard. Protect the file
with the machine's other credentials.
The command fails if the token is expired or invalid, or if it has already been used. Generate a new token in the dashboard and run the command again. Registration does not create or initialize a backup repository.
sudo vecta-agent run performs one pass: it authenticates, asks the control plane for jobs that are due,
runs those jobs sequentially, reports their results, and exits. If no jobs are due, it exits
without running restic. Cron invokes this single-pass command repeatedly; it is not a daemon. If
the configuration file is missing or incomplete, the command exits with an error telling you to run
sudo vecta-agent register --token <TOKEN> first.
Root privileges
On Linux, run operational commands with sudo, including register, setup, hooks add,
hooks publish, repo init, run, and update. The agent may need to read protected backup
sources and write system paths. hooks list and hooks validate are read-only and do not require
root; version and help also work without root. To intentionally run as the current user, put
--allow-non-root before the subcommand, for example vecta-agent --allow-non-root run. Access to
protected paths may then fail.
After registration
The agent appears online after it checks in. The list shows its name, 32-character hexadecimal ID, version, online state, and relative last-seen time. An agent that has not checked in recently appears offline. An offline banner appears across the dashboard and warns that its jobs will not run until it reconnects.
The agent reports its installed backup capabilities and safe hook catalog metadata during each
vecta-agent run. In Agents → Capabilities, check whether it is ready for PostgreSQL backups
and see which hooks are available. Reports older than 30 days are marked stale. After installing
tools or changing hooks, run sudo vecta-agent hooks publish to send an updated report now; this
command reports capabilities and does not start a backup.
To enable hooks, install and secure a local executable, then register it with
sudo vecta-agent hooks add. The default hook account is vecta-hook and must exist on the
machine; you can select an existing service account instead. Follow Database Backups and
Hooks for the catalog checks and privilege rules.
Files on the server
| Path | Purpose |
|---|---|
/root/.config/vecta/config.toml |
Agent configuration. |
/root/.config/vecta/credentials.toml |
Per-destination credentials; mode 600. |
/root/.config/vecta/pgpass-<fingerprint>.conf |
Connection-scoped PostgreSQL password; mode 600. |
/root/.config/vecta/restic.env |
Optional global Restic environment values. |
/etc/vecta/hooks.toml |
Root-controlled local hook catalog. |
/etc/cron.d/vecta |
Cron entry that invokes the agent every couple of minutes. |
/var/log/vecta-agent.log |
Agent output for troubleshooting. |
Keeping the agent updated
Use sudo vecta-agent update to check for and install the latest GitHub release. The command
downloads the binary and its SHA256SUMS file, verifies the binary before installation, and
replaces the installed file atomically. A checksum mismatch aborts the update without replacing
the current binary. The installed binary must be updated as root.
Use sudo vecta-agent update --check to compare versions without installing anything. To pin a
specific release, use sudo vecta-agent update --version vX.Y.Z; the version may also be supplied
without the leading v. An explicit version is installed even if it is older than the current
version. The running process remains valid while the file is replaced, and the cron job uses the
new binary on its next invocation.
The update command is for the installed binary. When running from source, it reports that the
binary cannot self-update and recommends git pull && pip install . instead.
Removing an agent
Deleting an agent permanently removes the agent, all of its jobs, run history, and snapshot-ID records. Repositories and their data are not deleted, but Vecta cannot list those snapshots afterward.
Lost API key
The API key is saved locally during registration and cannot be recovered from the dashboard. If the file containing it is lost, delete the agent and register it again. See Your agent API key before doing this.
What's next
Read The pull-based agent model, then create a job with Jobs.