Skip to content

Reference

Use this page for canonical commands, schedule syntax, statuses, destination formats, paths, and terms.

CLI reference

Command Purpose Notable flags
sudo vecta-agent register --token <TOKEN> Register the agent with a dashboard token. --token <TOKEN>
sudo vecta-agent run Perform one single-pass agent invocation. None.
sudo vecta-agent setup <JOB_ID> Configure a job destination and initialize its repository when needed. Job ID argument.
sudo vecta-agent repo init <DESTINATION> --generate Initialize a repository without a job. --generate
sudo vecta-agent update Update to the latest agent release. --check, --version vX.Y.Z
vecta-agent version Print the installed agent version. None.

On Linux, register, setup, repo init, run, and update require root. Prefix those commands with sudo as shown above. version and help do not require root. To intentionally run an operational command as the current user, pass --allow-non-root before the subcommand, for example vecta-agent --allow-non-root run; protected source or installation paths may not be accessible. Non-POSIX behavior is unchanged.

register --token <TOKEN> exchanges a single-use dashboard token for the agent ID, API key, and name, then writes them to /root/.config/vecta/config.toml when run as root. The file has mode 600. On success it prints the registered name or ID and the configuration path. The API key is saved in the configuration file and is not printed separately. Expired, invalid, or already-used tokens produce an error and a nonzero exit.

run performs one pass and exits: it authenticates, fetches the jobs the control plane says are due, runs them sequentially, and reports their status. It does not evaluate schedules locally and does not wait for another poll. With no due jobs it exits without running restic. Without a valid config file it exits with an instruction to register first.

setup <JOB_ID> fetches the job's non-secret destination configuration. It skips destination credential prompts when credentials are already stored locally; otherwise S3 prompts for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, and B2 prompts for B2_ACCOUNT_ID and B2_ACCOUNT_KEY, using hidden input. SFTP uses SSH keys and performs a non-interactive subsystem probe. If the repository is missing, setup initializes it, prints a generated repository password once, and waits for SAVED. It stores the destination credentials and repository password in ~/.config/vecta/credentials.toml with mode 600. Existing repositories are not overwritten.

repo init <DESTINATION> is the manual repository escape hatch. Without a password flag it prompts twice; --generate creates a password, --password <P> takes one from the command line, and --password-file <F> reads one from a file. A successful initialization saves the password in ~/.config/vecta/restic.env with mode 600. If the repository already exists, the command reports that fact and does not overwrite it or replace the stored password.

update resolves the latest GitHub release, downloads the binary and SHA256SUMS, verifies the SHA-256 checksum, and atomically replaces the installed binary. --check compares versions only; --version vX.Y.Z selects a specific release and accepts a version without the v prefix. Updates require root when using the installed binary. A checksum mismatch or download failure leaves the current binary in place. The cron job uses the replacement on its next run.

version prints the installed version, currently in the X.Y.Z form (for example, 0.5.0), and exits successfully.

Schedules

Presets are every 6 hours, every 12 hours, daily at 03:00 UTC, and weekly on Sunday at 02:00 UTC. A custom schedule uses five cron fields:

minute hour day-of-month month day-of-week

Examples:

0 3 * * *       daily at 03:00 UTC
*/6 * * * *     every six hours by minute-based cron
0 2 * * 0       Sunday at 02:00 UTC

Warning

Vecta evaluates cron in UTC. It has no timezone setting. A scheduled job starts when the agent checks in, usually within about two minutes of its due time.

Each job uses either an interval or cron. If cron is set, it takes precedence.

Statuses

Status or badge Meaning
pending Created but never run, or flagged but not picked up.
running Backup in progress.
success Last run completed and created a snapshot.
failed Last run errored, stopped, or timed out.
warning Snapshot created after zero files were processed.
stalled Running without progress for many hours.
force-run Flagged for the next check-in, including when disabled.
Pruned snapshot Reported as removed by the job's retention policy; Vecta does not offer a restore action for it.

Job options

  • Exclude patterns apply to filesystem jobs only. Enter one Restic pattern per line; an empty list means no exclusions. Patterns are passed as arguments, not expanded by a shell.
  • Snapshot retention is optional. The current Free plan supports an age window of 1–14 days; calendar keep rules are not available. When enabled, pruning is applied after a successful backup.
  • Snapshots opens a job-specific list of snapshot IDs reported to Vecta. It is not a complete inventory of the destination repository. See Jobs and Restoring Data.

Destination formats

Type Format
S3-compatible s3:https://<endpoint>/<bucket>
Backblaze B2 b2:<bucket>
SFTP sftp:<user>@<host>:<path>
Local path /path/to/repo

Files on the agent machine

Path Purpose
/root/.config/vecta/config.toml Agent configuration.
~/.config/vecta/credentials.toml Per-destination credentials; mode 600.
~/.config/vecta/restic.env Optional global restic environment file.
/etc/cron.d/vecta Cron schedule.
/var/log/vecta-agent.log Agent log.

Glossary

  • Agent: vecta-agent on your Linux server; it pulls work and runs restic.
  • Control plane: The hosted Vecta dashboard and coordination service at vectaapp.com.
  • Repository: An encrypted, deduplicated restic store.
  • Snapshot: A point-in-time record in a repository.
  • Deduplication: Restic stores repeated data once, so later runs can transfer fewer bytes than they process.
  • Repository password: The secret that decrypts one repository; it cannot be recovered by Vecta.
  • Registration token: A dashboard-generated, single-use token valid for 24 hours.
  • Agent API key: The one-time credential that identifies one registered agent.
  • Retention policy: A per-job rule that prunes older snapshots after a successful backup. The options available depend on the plan; the current Free plan offers age-based retention up to 14 days.

What's next

Use Troubleshooting for symptoms, or Restoring Data for restore commands.