Back up a Proxmox server
Proxmox VE backs up a virtual machine incrementally and deduplicated only when the backup goes to something that speaks the Proxmox Backup protocol. The Caryvane agent on a Proxmox node speaks it: Proxmox sees a backup server on the node itself, and every chunk it sends lands in the storage you chose, in exactly the layout a Proxmox Backup Server keeps. Backups are scheduled, run, browsed and restored from the Proxmox web interface, as they would be with a Proxmox Backup Server; Caryvane adds the storage, the catalogue, the alerts and a recovery key.
Caryvane is not a Proxmox product and does not contain Proxmox Backup Server. It implements the protocol Proxmox VE uses to talk to one, so Proxmox treats the agent as a backup server. Proxmox and Proxmox Backup Server are trademarks of Proxmox Server Solutions GmbH.
1. Install the agent on every node #
Proxmox runs a virtual machine's backup on the node the machine is on, and talks to the backup server at 127.0.0.1. So every node of the cluster needs the Caryvane Linux agent, enrolled for the customer who owns the cluster. It is the ordinary Linux agent; there is no separate Proxmox agent. On a Proxmox node it notices Proxmox by itself and reports the version, which is how Caryvane knows the machine can serve backups. Create the cluster in Caryvane from any one node. Once the cluster has a storage area, every other node whose agent is installed joins it by itself within a few minutes: it proves it belongs to the same Proxmox cluster with the storage token Proxmox shares between its nodes. Add node on the cluster's page still works for a node you want in straight away. If a machine you pick is on a node without the agent, the job dialog says so, and its backups show as failed runs naming the node rather than as completed.
- In Caryvane, create an enrollment token for the customer (Agents → Enroll Agent) and follow the Linux instructions on each node. The package is a
.debfor Debian, which is what a Proxmox node runs. - Wait for each node to show as online. A node on Proxmox shows its Proxmox version on its agent card; that is how the wizard knows it may host the datastore.
Each node is one agent, and is billed as one agent. There is no charge per virtual machine.
2. The cluster, its storage areas, and what to back up #
- Jobs → New job → Back up a Proxmox server. The first time, name the cluster and choose its first node. Add the other nodes from the Proxmox page afterwards; they need nothing else, because every node serves the same certificate.
- Back up machines: tick the VMs and containers (the list comes live from the cluster), or choose every machine, including ones created later, or every machine in a Proxmox pool. Choose the storage and a folder in it, when (daily, on chosen days, or every few hours) and how long to keep: a backup a day for N days, and optionally at least the last N.
For example: VM 146 kept 5 days in storage M, folder proxmox/vm146, and VM 170 kept 30 days in storage Y, are two jobs. Each storage and folder becomes its own storage in Proxmox, caryvane-name, with its own encryption key, registered by the agent within a few minutes. The same machine can be in two jobs to two storage areas, say nightly to the UK for a month and weekly to cheap storage for a year.
Caryvane writes each job into the cluster as a Proxmox backup job (Datacenter → Backup, marked caryvane-job in its comment) and keeps it in step: change it in Caryvane and the Proxmox job changes; delete it and the Proxmox job goes. Proxmox does the running, so its incremental backups, the guest-agent freeze and live migration all behave as normal. Do not edit those jobs in Proxmox; Caryvane puts them back. Backup jobs you make yourself in Proxmox to a Caryvane storage still work, and show on the Proxmox page as made in Proxmox.
Run now on a job starts its backups straight away. Every backup appears as a run of its job, with the size, what was sent and what was already stored. If no backup reaches a storage area within the interval you set, it is flagged as late.
For providers: backing up into a customer's own storage #
A provider's Proxmox server can back a customer's virtual machines up into the customer's storage, for example their own UK bucket. The customer allows it first: on their storage target, Storage → … → Allow my provider's Proxmox servers. Only storage of customers beneath the provider can be chosen, never another provider's or a sibling's, and the provider's own storage needs no tick.
- The job is the customer's: it appears in their jobs list with its runs and status. Only the provider can change, run or delete it; the customer cannot reach the Proxmox server or back up anyone else's machine.
- Each customer has their own recovery key, which reads only the backups in their storage. The customer can download it themselves; the provider can too, for customers beneath them.
- Ticking the box gives the provider's Proxmox servers access to that storage. Unticking it stops them within five minutes: the storage is no longer served and its backup jobs are removed from the cluster. Backups already taken stay.
3. The encryption key: back it up now #
The storage is created with an encryption key that Proxmox generates and keeps in /etc/pve/priv/storage/. Every chunk is encrypted on the node before it leaves; Caryvane and the storage only ever hold ciphertext. Proxmox shows the key once and asks you to back it up: do that, into a password manager or a printed copy kept away from the cluster. A cluster that is lost takes the key with it.
There is a second way back. The storage entry also carries a Caryvane master key, and Proxmox encrypts a copy of the data key to it inside every backup. Caryvane keeps the private half, encrypted, and a manager can download it from the job page as a recovery key. With the recovery key and the Proxmox tools, every backup is readable again even if the cluster and its key are gone. Download it once and keep it with the first one; the download is recorded in the audit trail.
Never run pvesm set … --encryption-key autogen on the Caryvane storage: it replaces the key silently, and every earlier backup then needs the recovery key.
4. What is backed up and how #
- Virtual machines: every disk, the configuration and the firewall rules, as Proxmox sends them. Proxmox reads the whole disk the first night and only the changed blocks after that (its dirty bitmap), and the agent stores each 4 MiB chunk once however many machines or nights share it.
- On Ceph and other raw storage the bitmap lives in the running machine; after a migration, a shutdown or a node reboot Proxmox reads the whole disk again but still sends only chunks the storage does not already have. The run shows read, sent and reused separately, so a cluster that migrates nightly is not mistaken for one that never gets an incremental.
- Application consistency comes from the QEMU guest agent inside the virtual machine, exactly as with a Proxmox Backup Server: with it installed, Proxmox freezes the guest's file systems for the snapshot; without it the backup is crash-consistent.
- Containers (LXC) and host backups made with
proxmox-backup-clientwork the same way.
Every Proxmox backup appears in Caryvane as a run of the datastore's job, one per machine, with the size, the chunks sent and the bytes reused. The job page lists every snapshot of every machine.
5. Restoring #
Restores are done in the Proxmox web interface, exactly as from a Proxmox Backup Server. Caryvane serves the backups to Proxmox; there is no restore button in Caryvane for Proxmox machines. The cluster's page in Caryvane repeats these steps with its own storage names.
A whole machine #
- In Proxmox, under any node, click the Caryvane storage. Its name starts
caryvane-(for examplecaryvane-test); the storage area's card in Caryvane shows it. - Open Backups. Every backup of every machine on that storage area is listed, newest first.
- Pick the backup and click Restore.
- Choose where it goes. A new VM ID restores alongside the original, which is the safe choice when you only want to look. The machine's own VM ID replaces it; Proxmox asks you to stop the machine first and overwrites its disks.
- Pick the target storage for the disks (for example your Ceph pool) and start the restore. Progress shows in Proxmox's task log at the bottom of the screen.
From the command line, qmrestore caryvane-test:backup/vm/153/2026-10-18T17:40:45Z 9153 does the same (pct restore for a container). On our own cluster a 50 GiB machine restored from a cloud bucket in about half a minute and booted normally.
Single files and folders #
- Open the Caryvane storage and Backups as above, pick the backup and click File Restore.
- Proxmox starts a small temporary helper to read the backup. Open the disk (for example
drive-scsi0), then the partition that holds the files; a swap partition cannot be opened. - Browse to the file or folder and click Download. A folder downloads as a zip.
Nothing is written to the running machine; copy the file back yourself. The first browse of a backup takes a little longer while the helper starts.
If the cluster is lost #
The backups are safe in the storage, but each one is encrypted on the node with a key Proxmox kept on the cluster (/etc/pve/priv/storage/caryvane-<name>.enc). If you kept a copy of that file when Proxmox showed it, put it back on the new cluster and restore as normal. If not, the customer's recovery key in Caryvane recovers it:
- Install the Caryvane agent on a Proxmox node of the new cluster, add the node to a cluster in Caryvane, and add the same storage, bucket and folder as a storage area. The backups appear under the new
caryvane-storage in Proxmox. - On the cluster's page in Caryvane, click Recovery key next to the customer and save the key as
master.pemon the node. - Fetch the encrypted key that every backup carries, and unlock it with the recovery key:
proxmox-backup-client restore vm/153/2026-10-18T17:40:45Z rsa-encrypted.key rsa-encrypted.key \ --repository 'USER@127.0.0.1:8007:DATASTORE' proxmox-backup-client key import-with-master-key old.enc \ --master-keyfile master.pem --encrypted-keyfile rsa-encrypted.key --kdf none
USERandDATASTOREare theusernameanddatastorelines of the storage in/etc/pve/storage.cfg; the password is in/etc/pve/priv/storage/caryvane-<name>.pw(give it asPBS_PASSWORD), andPBS_FINGERPRINTis the storage'sfingerprintline.--kdf noneleaves the recovered key without a password, which is what a Proxmox storage takes. - In Proxmox, Datacenter → Storage, edit the Caryvane storage, Encryption, and upload
old.encas its key. The old backups now restore as normal.
Keep each customer's recovery key somewhere that survives losing the cluster. Downloading it is recorded in the audit trail.
Snapshots can be protected and annotated in Proxmox. Each job's retention prunes its own machines' backups; a storage area's never keep longer than, if set, removes older ones on top, never the newest of a machine and never a protected one. Proxmox's own tools work too: proxmox-backup-client pointed at 127.0.0.1:8007 on any node, with the storage's token.
Boot checks: testing that backups restore #
A backup that has never been restored is a hope. A boot check restores a machine's newest backup on the cluster as a throwaway copy, starts it, asks it who it is, takes a picture of its screen and deletes it again, on a schedule, without anyone watching. The Proxmox page then shows a badge beside each machine: Booted 2 days ago (green), Booted, no guest agent (amber), Boot check failed (red) or Not checked. Click a badge for the screenshot, the host name and operating system the machine gave, which backup was tested and the run log.
A green badge means the copy booted and answered through the QEMU guest agent. It does not test the applications inside, and it is not a promise that every file is intact; it is strong evidence that the backup is a working machine.
Setting it up #
- On the cluster's page in Caryvane, Boot checks → Set up boot checks.
- Tick the machines to check. Nothing is checked unless you tick it. Machines are checked one at a time, smallest first.
- Name the Proxmox storage the copies are restored to, for example
local-lvmor a Ceph pool. It must exist on the node that runs the checks (shown on the card; it is the node that writes the cluster's backup jobs). - Set the size cap (200 GB unless you change it), how long a machine has to boot (10 minutes) and the days and time. The default is Saturdays at 12:00 UTC, away from the nightly backups; if backups are running when it starts, it waits for them to finish.
Check now runs it straight away. Each check is also a run of the boot check job, with its log, in the jobs list.
What a check does to the cluster #
- The copy never touches your network. It is restored with a new VM ID between 9100 and 9199, every network card is set to disconnected, and the agent reads the configuration back from Proxmox and refuses to start the copy unless every card shows disconnected. There is no setting to turn this off: a domain controller restored from last week and started on the live network would replicate stale passwords and deleted objects back into the real domain. A machine with a PCI or USB device passed through is not started at all.
- It only starts when there is room. The copy is made only when at least a fifth of the target storage, or 50 GB, whichever is more, stays free afterwards, when the machine is under the size cap, and when the node has the machine's memory free with 4 GB to spare. Otherwise the machine shows Not checked with the reason.
- It is always removed. The copy is named
cv-verify-name, taggedcaryvane-verify, never starts with the node and is not in HA. It is stopped and destroyed, with its disks, when the check ends, however it ends. - If the agent is stopped mid-check (a reboot, an update), it recorded the copy before making it, and removes it the next time it starts. A VM in that range with the tag that the agent has no record of making is never deleted: you get an alert to look at it yourself. A copy that could not be removed always sends an alert, whatever your notification settings say.
Without the QEMU guest agent inside the machine the badge can only say it booted, so it is amber: open the screenshot to see how far it got. Installing the guest agent in each machine also makes its backups application-consistent.
The cluster can also boot-check physical Windows machines: a whole-machine backup can be restored to a throwaway VM on a node on a schedule, with the same isolation, VM ID range and clean-up, and a whole-machine restore point can be restored to a lasting Proxmox VM.
The full screenshot is kept in the customer's own storage, next to the backups (verify/VMID/ in the storage area's folder); Caryvane keeps only a small thumbnail. Failed checks are emailed to the addresses in Settings → Notifications; switch off Boot check failed there if you do not want them.
6. Which storage, and what to expect #
Any Caryvane storage target works. The difference is speed:
- Object storage (Amazon S3, Wasabi, Backblaze B2, Azure Blob, Cloudflare R2 and the like): chunks stream straight up, in parallel. The usual choice.
- A share or server (SMB, SFTP, FTP, a local folder on the node): one file per chunk, in the same layout a Proxmox Backup Server keeps on disk. Fast restores on the LAN. An ordinary Caryvane file job on a Windows machine that sees the share can copy the datastore folder to the cloud each night; chunks never change, so the copy is only the night's new ones.
- Services that take one file per call (Egnyte, OneDrive, SharePoint, Dropbox, Google Drive): every chunk is one upload and the service rate-limits, so the first full backup of a large machine can take a day. Nightly incrementals are small and fine. The wizard says so when you pick one.
If you cannot change the cluster yet #
Two routes work today without anything on the Proxmox nodes. Install the Caryvane agent inside each virtual machine, which gives file and application backup (including Hyper-V, SQL Server and Active Directory on Windows guests) but not whole-machine restore. Or schedule vzdump on a node into a local directory and back that directory up with an ordinary Caryvane file job; every night's archive is a full one, so this suits small machines.