Skip to content

Reference

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

CLI reference

Command Purpose Notable flags
vecta-agent register --token <TOKEN> Register the agent with a dashboard token. --token <TOKEN>
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.

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.

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.
  • Prune and retention: Repository cleanup policies. Vecta does not manage them today; use restic manually.

What's next

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