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-agenton 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.