Skip to content

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.
  • flock from util-linux.
  • Outbound HTTPS access to vectaapp.com.
  • restic, supplied by the recommended installer or installed separately for a manual setup.

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:

vecta-agent register --token <TOKEN>
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.

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 vecta-agent register --token <TOKEN> first.

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.

Files on the server

Path Purpose
/root/.config/vecta/config.toml Agent configuration.
~/.config/vecta/credentials.toml Per-destination credentials; protect with mode 600.
~/.config/vecta/restic.env Optional global restic environment values.
/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.

The update command is documented in Reference after the agent CLI behavior has been verified.

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.