Virt Backup · Documentation

How Virt Backup works

Virt Backup is a desktop app and background agent for backing up, checking, scheduling, and restoring Libvirt virtual machines.

Agent-based

The agent does the backup and restore work in the background. The desktop app is the control panel.

Deduplicated

Backups are stored as manifests and unique data blocks, so repeated data is not stored again.

Recoverable

Restore entries can be checked before you restore, and restores can target a selected server and storage.

First run

Download the Linux or macOS tarball from the Downloads page.
Unpack it with tar -xzf virtbackup-<platform>-<version>.tgz and open the extracted directory.
Start the agent on the machine that should run backup and restore jobs. The recommended option is ./install_agent_user_service.sh, which installs and starts the user service. You can also start it manually with ./virtbackup-agent.
Open the desktop app with ./virtbackup and select or add the agent in Settings.
Set the filesystem storage path in Settings first. The local filesystem storage entry already exists, but it needs a writable path before the other app tabs are available.
Add one or more Libvirt servers using SSH connection details. The SSH user needs read and write access to the Libvirt image paths; using root is preferred.
Add optional extra storage destinations such as SFTP or Google Drive.
Run a backup, then perform a restore check so you know the data is usable.

Core concepts

Agent

The agent exposes the local API used by the desktop app. It keeps running when the GUI is closed and owns long-running jobs.

Server

A server is a Libvirt host managed over SSH. Virt Backup reads VM inventory and runs backup, restore, and VM actions through that host.

Storage

Storage is where manifests and deduplicated blocks are kept. The current app supports filesystem, SFTP, and Google Drive storage.

Manifest

A manifest describes a backup point: VM metadata, XML, disk list, timestamps, and the data blocks needed for restore.

Running backups

Open the Backup tab, choose a server, choose a storage target, and start a backup for the VM you want to protect.

Running jobs show progress, speed, storage target, and estimated time remaining.
If a Virt Backup-created overlay is detected, backup is disabled until cleanup is run.
Backups can be stored locally, on SFTP, or in Google Drive.
Deduplication means unchanged blocks do not need to be written again.

Storage destinations

Storage is configured from Settings. Use New storage to add a destination, or edit and delete existing entries from the storage list.

Filesystem

The filesystem storage entry is created by default. Set its writable path in Settings before using the backup, restore, schedule, and queue tabs.

SFTP

Stores backups on an SFTP server. Configure host, port, username, password, and base path.

Google Drive

Connect through the browser. Virt Backup manages its own Drive files and keeps token details out of the normal editor.

Restoring VMs

Open the Restore tab, select the restore server, storage, VM, and backup date, then start the restore.

Restore can overwrite an existing VM, auto-rename on conflict, or define XML only when that is supported.
The UI shows why restore is disabled when required selections, tools, storage, or disks are missing.
Restore progress shows transferred data and speed while the job is running.

Checking backup data

Use checks before relying on a backup. A quick check validates blob presence by building storage directory listings during the check and reusing those listings for the rest of that check. A full check performs a deeper validation of backup data.

Checks are available from the Restore tab for the selected backup entry.

Schedules and queue

Schedules can run recurring backup or restore jobs. You can create backup schedules, restore schedules, and all-VM schedules from the Schedules tab.

Schedules can wait for running jobs instead of failing immediately.
The Queue tab shows running and waiting schedule runs.
Manual schedule runs use the same safety guards as automatic runs.

Account and notifications

The desktop app can sign in with a Virt Backup account for account features and email notifications. Email notifications require an active subscription. The agent can also send Ntfy me notifications when configured.

Backup and restore jobs remain agent-driven. Always test restore behavior in your own environment before depending on any backup system.