Documentation
Install the agent, create a config, run backups, and restore when needed.
Quick start
Download the agent, create a config, run your first backup, and confirm it appears in the portal.
# 1) Download the agent
# https://backupverified.com/download-agent.html
# 2) Create or edit your config file
nano bv-agent.yml
# 3) Paste your agent_key and client_encryption_key_b64 into bv-agent.yml
# 4) Validate your config
bv-agent validate-config -config bv-agent.yml
# 5) Run a backup
bv-agent backup -config bv-agent.ymlPaste your agent_key and client_encryption_key_b64 into the file and keep both safe.
Contents
Jump to the section you need.
Installation
Download the agent for your operating system, then make it executable.
# Example (macOS / Linux / FreeBSD)
chmod +x ./bv-agent
# Sanity check (after you have a config)
bv-agent validate-config -config bv-agent.ymlDownloads and CLI install commands are available on the Download Agent page.
Configuration file
The agent runs a command that writes backup data to STDOUT. The agent reads from STDOUT, compresses and encrypts locally, then uploads your encrypted backup to Backup Verified Managed Storage.
Streaming requirement
Commands must stream to STDOUT. For tar archives, use -cf - (the trailing - means “write to STDOUT”). Note: the agent already compresses the stream, so you usually should not use tar’s -z option. Tip: ~ is not expanded because the agent does not run a shell. Use full paths or run from the target directory.
Minimal config
bv:
api_base: "https://backupverified.com"
timeout_seconds: 30 # API calls
work_timeout_seconds: 0 # 0 = no overall deadline
upload_timeout_seconds: 0 # 0 = no upload-only deadline
agent_key: "YOUR_AGENT_KEY"
client_encryption_key_b64: "YOUR_CLIENT_ENCRYPTION_KEY_B64"
backup:
source_key: "dir_backup"
name: "Directory Backup"
description: "Archive current directory via tar"
source:
type: "tar"
backup_command: "tar -cf - ."
Field reference
| Key | Description |
|---|---|
| bv.api_base | Base URL for Backup Verified API calls. |
| bv.timeout_seconds | Timeout for API calls used during backup initialization and completion. Default recommended: 30. |
| bv.work_timeout_seconds | Optional overall deadline for dump/encrypt/upload. Use 0 for no overall deadline (recommended for large backups). |
| bv.upload_timeout_seconds | Optional deadline for upload only. Use 0 for no upload deadline. |
| agent_key | Authenticates the agent to Backup Verified. |
| client_encryption_key_b64 | Client encryption key (base64). Keep it safe—without it, backups cannot be decrypted. |
| backup.source_key | Stable ID for this backup source (used for grouping/history). Avoid changing it casually. |
| backup.name | Friendly name shown in the portal. |
| backup.description | Optional description shown in the portal. |
| source.type | Label shown in the portal (examples: mysql, postgres, tar). |
| source.backup_command | Command that writes backup bytes to STDOUT. The agent runs it and uploads the encrypted result. |
Running the agent
Run the agent from the directory containing your config file.
bv-agent validate-config -config bv-agent.yml
bv-agent backup -config bv-agent.ymlAfter a successful run, you should see the backup listed in your portal dashboard.
Backup sources
Backup Verified works with any tool that can stream backup data to STDOUT. For copy-and-paste recipes, see the Recipes page.
Databases
mysqldump, pg_dump, and other logical exports.
Files & directories
tar streams of app servers, uploads, and config snapshots.
Anything that streams
If it can write bytes to STDOUT, the agent can back it up.
Scheduling
Most users schedule backups using cron or a system scheduler.
# Example cron (daily at 2:15am)
15 2 * * * /usr/local/bin/bv-agent backup -config /path/to/bv-agent.ymlVerification
Backup Verified verifies the integrity of stored backups and reports verification status in the portal.
Upload completeness
Confirms the backup was fully received and stored.
Integrity checks
Validates the stored backup remains consistent over time.
Restore
Download the encrypted backup from the portal, decrypt locally, then restore using your normal tools.
# Decrypt to a file (example)
bv-agent decrypt --in backup.bin.enc --out backup.out --config ./bv-agent.yml# If your backup is a tar stream:
tar -xf backup.out -C /path/to/restore/# If your backup is a SQL dump:
mysql -u root -p database_name < backup.outSecurity model
Backups are compressed and encrypted locally before any data is uploaded. Backup Verified cannot read your backup contents.
Keys stay with you
Keep multiple secure copies of your encryption key.
Agent authentication
The agent uses your agent key to authenticate to the service.
Troubleshooting
The command runs, but no backup appears in the portal
Confirm your agent_key and bv.api_base are correct, then run validate-config.
tar backups fail or produce empty uploads
Make sure tar writes to STDOUT using -cf -.
Timeouts
bv.timeout_seconds applies to API calls. For long backups, leave work_timeout_seconds and upload_timeout_seconds at 0 (no deadline), or set them if you want a hard cap.
FAQ
Can Backup Verified read my backups?
No. Backups are encrypted locally before upload.
What happens if I lose my encryption key?
Backups cannot be decrypted without the key. Store multiple secure copies.
How fast are backups?
Can I use zip?
Yes. Any command that writes bytes to STDOUT works. For example: zip -r - . (The agent will still compress and encrypt the stream; zip is mainly listed here for familiarity.)
Do I need to change anything in Backup Verified to back up a new system?
Create a new config with a new backup.source_key and a streaming command for that system.