cv4pve-autosnap: scheduled Proxmox snapshots with per-label retention

The problem: snapshots nobody takes or deletes

A snapshot is the quickest way back after a broken upgrade or a bad change inside a guest, and the documentation makes the point that Proxmox VE takes one in a click, but only when someone remembers to click, and it never removes the old ones.

Both halves of that are real problems. A snapshot nobody takes is no snapshot. A snapshot set nobody prunes is a disk filling up until something fails, and the failure will happen in the guest that has the least room to complain.

cv4pve-autosnap takes the snapshot of every guest you select and removes the oldest ones of the same label, so a policy like every two hours, keep 10 stays at ten snapshots per guest. The documentation says you can run it from cron or the Task Scheduler, or right before an upgrade.

The design constraint that makes it usable on an existing cluster is that it runs outside the nodes and uses only the Proxmox VE API: nothing to install on the cluster, no SSH, no root shell. That is a different deployment story from the usual approach of putting a script on the hypervisor host, and it means the tool can be run from a laptop, a container, or a cron job on an existing management box.

The audience is Proxmox operators, and the project is part of a wider suite from the same author, with the homepage at corsinvest.it and the documentation on the project's GitHub Pages site.

Retention per label, guest selection, and the storage guard

The features list is where the operational detail lives.

Retention per label is the core. The labels can be hourly, daily, weekly or any name you like, and each label keeps its own number of snapshots per guest. That is the design that makes the tool more than a cron wrapper: an hourly label with a keep count of 24 and a daily label with a keep count of 7 can run side by side against the same guest without either deleting the other's snapshots.

Guest selection is resolved at every run. You can choose by ID, by name, by range, by node, by pool or by tag, and you can exclude things. The documentation is explicit that the set is resolved on each run, so a migrated guest or a newly tagged guest is picked up with no change to the configuration. That is a meaningful design choice, since the alternative is a static list that goes stale the first time you move a VM.

The storage guard is the safety net. A guest is skipped when a storage holding its disks is used above 95 percent, or whatever threshold you set. On a busy cluster this is the difference between a snapshot job that protects you and one that fills a volume and takes the cluster down with it.

The remaining features are hook scripts, consistent snapshots, parallelism, a dry run and node failover. Hook scripts run at every phase with the guest, the label and the result in environment variables, and there are ready-made templates plus a metrics sender in the hooks/ directory.

Installing it and the first run

The quick start covers three platforms, and the Windows path is a single package manager call:

# Windows
winget install Corsinvest.cv4pve.autosnap

# Linux (other platforms and packages: see the documentation)
wget https://github.com/Corsinvest/cv4pve-autosnap/releases/latest/download/cv4pve-autosnap-linux-x64.zip
unzip cv4pve-autosnap-linux-x64.zip && chmod +x cv4pve-autosnap

The tool is also on NuGet as Corsinvest.ProxmoxVE.AutoSnap.Api, and there is an AUR package for Arch. The project markets the package set on corsinvest.it.

Then there are the two commands, and the first one is the important one:

# See what would happen, then take the snapshots
./cv4pve-autosnap --host=pve01 --api-token='autosnap@pve!snap=<uuid>' --vmid=@all --dry-run snap --label=daily --keep=7
./cv4pve-autosnap --host=pve01 --api-token='autosnap@pve!snap=<uuid>' --vmid=@all snap --label=daily --keep=7

The dry run shows what would be created and removed, which is the sensible way to find out whether your label and keep values mean what you think before you let it delete anything.

The argument order is worth internalising because it is a common source of confusion. Global options such as --host, --vmid and --max-parallel go before the command, and command options go after it. The API token needs the four privileges listed on the permissions page, so the token string in the examples is a placeholder for a token you create yourself with a specific privilege set rather than a broad one.

Reading the status output

The status command shows what is on the cluster, and the documented output is worth reading because it tells you how the tool sees the world.

$ cv4pve-autosnap --host=pve01 --api-token='autosnap@pve!snap=…' --vmid=@all status
+-------+------+-------------------+-------------------------+-------------------------+-----------------+-----------+
| NODE  |   VM | TIME              | PARENT                  | NAME                    | DESCRIPTION     | VM STATUS |
+-------+------+-------------------+-------------------------+-------------------------+-----------------+-----------+
| pve01 |  105 | 26/09/28 07:00:02 | before-upgrade          | auto2hourly260928070002 | cv4pve-autosnap |           |
| pve01 |  105 | 26/09/28 09:00:04 | auto2hourly260928070002 | auto2hourly260928090004 | cv4pve-autosnap |           |
| pve01 | 1000 | 26/09/28 07:00:03 | no-parent               | auto2hourly260928070002 | cv4pve-autosnap |           |
| pve02 |  203 | 26/09/28 07:00:57 | no-parent               | auto2hourly260928070002 | cv4pve-autosnap |           |
+-------+------+-------------------+-------------------------+-------------------------+-----------------+-----------+

The columns are the node, the VM ID, the creation time, the parent, the snapshot name, the description and the VM status.

Two of them carry the whole retention model. The parent column shows whether a snapshot has a parent, so a chain of hourly snapshots shows the previous one as parent while a first snapshot in a chain shows no-parent. The name column encodes the label and the timestamp, auto2hourly260928070002 being an auto-generated name for a two-hourly snapshot taken at 07:00:02 on 28 September 2026. The before-upgrade parent in the first row is a manually created snapshot that the tool treats as an ancestor, which matters because the tool prunes by label, and that row's name is a different label, so it survives.

The VM STATUS column is there for a reason too, and the documentation mentions warning when a VM has the QEMU guest agent off, which relates to the consistency option.

Consistency, the QEMU guest agent, and parallel snapshots

Snapshot consistency is the part that most people get wrong, and the project has a page dedicated to it.

The consistent snapshots feature is optional and is enabled with --state, which captures the RAM state as well as the disk state. The catch is the guest agent: the tool warns when a VM has the QEMU guest agent off, because without the agent the guest cannot be told to flush its filesystem and freeze its applications, so the snapshot is a crash-consistent image rather than a clean one.

The documentation also mentions fsfreeze hooks for databases, which is the practical answer for a database guest where you need the application to quiesce. The hook script mechanism covers this generally, since a hook can run a database-specific flush command at the phase you need.

Parallelism comes from --max-parallel, which lets several guests be snapshotted at the same time. That is a throughput decision with a storage consequence, since parallel snapshots on a busy volume will spike the write load at the same moment.

Then there is the cluster behaviour that matters most for a scheduled job. The tool keeps running with a node down: give it more than one host and it uses the first that answers. For a cron-driven job across a cluster, that turns a node failure from a missed backup window into a delay.

The other operational pieces are the dry run, which shows what would be created and removed, and the hook scripts, which run at every phase with the guest, the label and the result in environment variables, with ready-made templates and a metrics sender in the hooks/ directory so the job can report into whatever you already monitor.

A snapshot is not a backup, and the tool says so

The documentation puts a warning directly under the introduction, and it is the most important operational fact about this project.

A snapshot is not a backup. It lives on the same storage as the disk: if the storage is lost, so are its snapshots. The documentation points you at the Proxmox VE backup documentation for that job.

That is not a flaw in cv4pve-autosnap, it is the nature of what it automates. The tool automates the recent restore point, the one you take before an upgrade so you can roll back in a minute. The off-site copy, the one that survives losing a disk, is a different mechanism and a different schedule, and Proxmox VE has its own for it.

So the sensible deployment is both. The autosnap tool gives you the dense recent history per label, hourly and daily, for the fast rollback case, and the built-in backup job handles the case where the whole storage volume disappears.

The related tool in the same suite completes the picture. cv4pve-node-protect is for saving the configuration of the nodes, so a cluster whose nodes are reconfigured can be put back. cv4pve-autosnap is for the guests. The documentation makes that division explicit, and it is the right way to think about it.

There is also a web interface option. cv4pve-autosnap also runs inside cv4pve-admin as its AutoSnap module, which is aimed at people who prefer a web interface with schedules, run history and webhooks to a cron job.

Where cv4pve-autosnap is the wrong tool

The first limit is the one the documentation itself puts in a warning box. If your restore plan depends on these snapshots surviving a storage failure, this tool does not help you, and running it more often makes the disk fill faster rather than making you safer.

The second is the API token. The tool needs a token with four specific privileges against your Proxmox VE API, and a scheduled job holds that credential on a machine that is probably not a Proxmox node. The permissions page is the thing to read first, and creating a narrowly scoped token for a snapshot job is the right practice, but it is a credential to manage and to rotate.

The third is that the guest set is resolved at every run. That is a feature for catching newly tagged guests, and it is a hazard if a tag means something slightly different to someone else, since a stray tag can pull a new guest into a policy that deletes snapshots by label.

The fourth is the scope of the tool itself. It is a snapshotter with retention. It is not a configuration backup, it is not an off-site copy, and it is not a monitoring system. The suite has other tools for the first and second.

Compare that with taking snapshots by hand through the Proxmox VE interface. The difference in approach is that cv4pve-autosnap reaches in over the API, so it can act on guests across a cluster, apply a label scheme, and run on a schedule without anyone remembering to click. If you only have one node and you always remember to click, the native path is less machinery. If you have a cluster and a schedule, this is the tool that fits.

Licence, packaging and what to check before the first schedule

cv4pve-autosnap is released under the GPL-3.0 licence, with the text in the LICENSE.md file at the repository root, and the repository also carries a 3rd-party-licenses.md file for the components it bundles. GPL-3.0 is a strong copyleft licence, so if you distribute a modified build of the tool you take on the corresponding source obligation. Read both files yourself for the exact terms, since the third-party list is the part that changes with a dependency bump.

The packaging is broad because the tool is meant to run wherever the operator is. It is on winget for Windows, on the AUR for Arch, on NuGet as Corsinvest.ProxmoxVE.AutoSnap.Api, and as a downloadable zip for Linux, with the project stating that other platforms and packages are covered in the documentation. The source tree confirms the shape of a modern.NET project, with a solution file, a Directory.Build.props, a Directory.Packages.props, separate src/ and tests/ directories, a packaging/ directory, a hooks/ directory, a skills/ directory and a docs/ directory.

The skills/ directory is worth a note, because the documentation table lists a page for AI assistants covering Claude Code, Codex and the cv4pve-autosnap skill. The repository carries a skills/ directory to match.

The release history shows active work. v2.1.1 came on 2026-04-20, v2.2.0 on 2026-09-30 and v2.2.1 on 2026-10-03, and the last push was on 2026-10-20, so the tree is days old relative to today.

What to check before you put it in cron is a short, concrete list. Read the permissions page and create a dedicated user and API token with only the four required privileges, not an existing admin token. Run the status command and the dry run against the real cluster and read the output carefully, since that is where you see which guests the selectors actually match. Then set the storage guard threshold deliberately for your volumes rather than leaving the default, and add the hook script for any guest running a database, so the snapshot is consistent rather than merely fast.

Editorial conclusion

cv4pve-autosnap fits a Proxmox operator who wants recent restore points without clicking the snapshot button every time, and who wants per-label retention so hourly and daily policies can coexist. It does not fit anyone treating snapshots as backups, since the project states plainly that a snapshot lives on the same storage as the disk. Before you deploy it, read the permissions page and create a dedicated API token with only the four required privileges, run --dry-run first on a real cluster, and set the storage guard threshold deliberately, because a tool that silently skips a guest on a full volume is the failure mode you want to hear about rather than discover later.

Frequently asked questions

Official sources

1. Corsinvest/cv4pve-autosnap on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases