ProxSnap - A Snapshot Manager for Proxmox VE Clusters

Snapshots are one of the most useful safety mechanisms in virtualized environments. They make it easy to roll back changes, reduce risk during upgrades, and provide confidence when testing or migrating workloads. Proxmox VE supports snapshots for both virtual machines and containers, and on a single guest level this works well and reliably.

The problem starts once a setup grows into a real Proxmox VE cluster. There is no native way to get a complete overview of snapshots across all nodes in a cluster. Simple but important questions are surprisingly hard to answer. Which nodes currently have snapshots? Which VMs or containers still carry old snapshots? How many snapshots exist in total and how old are they? Answering these questions usually means clicking through every node and every guest manually. Over time, snapshots tend to pile up quietly. A snapshot created before a quick change or update is often forgotten. Weeks or even months later it may still exist, consuming storage, affecting performance, or complicating backups, without being obvious at first glance. Not only my customers but also I had to deal with such situations in my BoxyBSD project.

ProxSnap Installation

Installing ProxSnap is deliberately kept straightforward and consistent with the rest of the Prox Tools collection. The preferred installation method is via the gyptazy open source solutions Debian repository, which provides ready to use packages for both Debian and Proxmox VE based systems and allows ProxSnap to be deployed within minutes.

Using the repository ensures that ProxSnap is fully integrated into the system package management. Updates are handled automatically through the standard package upgrade workflow, making it easy to keep the tool up to date without additional maintenance overhead or manual intervention.

For environments where a repository based installation is not desired, ProxSnap can also be installed by downloading the prebuilt .deb package directly. The package can be installed using either apt or dpkg, depending on operational requirements or personal preference, and does not require any compilation or additional dependencies.

Both installation options result in a clean, native system package that installs the standalone ProxSnap binary and follows standard Debian filesystem conventions. This approach ensures a smooth installation and removal process and keeps ProxSnap aligned with other Prox Tools, allowing it to blend seamlessly into existing Proxmox VE environments.

Note: This software is provided “as is”, without warranty of any kind, express or implied. Use of this software is entirely at your own responsibility. The authors and contributors shall not be held liable for any direct or indirect damages resulting from its use.

ProxSnap Debian Mirror

The easiest way to get started with ProxSnap is by installing it through the gyptazy open source solutions Debian repository. This method is recommended because it integrates ProxSnap directly into the system package management and ensures that updates are delivered automatically through the regular upgrade process.

By using the repository, no manual downloads or build steps are required. Once the repository is added, ProxSnap can be installed like any other system package, making the initial setup quick and reliable. The following snippet shows how to add the repository and install ProxSnap on Debian or Proxmox VE based systems.

echo "deb https://repo.gyptazy.com/stable /" > /etc/apt/sources.list.d/proxlb.list
wget -O /etc/apt/trusted.gpg.d/proxlb.asc https://repo.gyptazy.com/repository.gpg
apt-get update && apt-get -y install proxsnap

ProxSnap Debian Package

As an alternative, ProxSnap can also be obtained by directly downloading the statically compiled Rust binary packaged as a Debian .deb file. This option is useful for environments where adding an external repository is not desired or possible.

The downloaded package can be installed using either apt or dpkg and does not require any additional dependencies or build steps. This makes it a quick and self contained installation method while still providing the same standalone ProxSnap binary and full functionality.

wget https://cdn.gyptazy.com/debian/proxclmc/proxsnap_1.0.0_amd64.deb
dpkg -i proxsnap_1.0.0_amd64.deb

ProxSnap Config

ProxSnap is built to fit seamlessly into existing Proxmox VE environments while keeping configuration effort to a minimum. By default, it automatically reads its configuration from /etc/proxsnap/proxsnap.yaml, allowing ProxSnap to be deployed system wide without the need for additional command line arguments.

If a different configuration location is required, or if multiple setups need to be tested, the default path can be overridden using the -c option together with a custom file path. This is particularly useful in development environments or when running ProxSnap in isolated or temporary setups.

In environments where ProxLB is already in use on the same node, the existing configuration can be reused without modification. ProxSnap follows the same configuration structure, making it possible to share credentials and connection settings across tools. This keeps configuration consistent within the Prox Tools collection and avoids unnecessary duplication.

The configuration itself defines how ProxSnap communicates with the Proxmox VE API. Access is handled through an API token, providing a secure and permission controlled authentication mechanism. Options such as SSL verification and request timeouts can be adjusted to match the specific requirements of the environment. Below, you can find an example config:

proxmox_api:
 hosts: virt01-de-ne01.dev.gyptazy.com
 user: proxsnap@pam
 token_id: test
 token_secret: ac1079bb-3333-3333-3333-8a3262da6077
 ssl_verification: False
 timeout: 10

The hosts setting specifies the Proxmox VE node or API endpoint that ProxSnap should connect to. Together, the user, token_id, and token_secret form the API token used for authentication, ensuring access is both secure and permission controlled. Depending on the certificate setup in the environment, SSL verification can be enabled or disabled, while the timeout option defines how long ProxSnap waits for responses from the Proxmox VE API.

This clear and familiar configuration layout makes ProxSnap easy to adopt, particularly in environments where other Prox Tools are already in use. Once the configuration is in place, no additional setup is required and ProxSnap can immediately start delivering cluster wide snapshot visibility.

ProxSnap Token Permissions

For basic operation, where ProxSnap only needs to list virtual machines and inspect their snapshots, the permission VM.Audit is required. This allows read-only access to VM configuration and snapshot metadata.

If the optional cleanup functionality is enabled, where ProxSnap is allowed to delete old or expired snapshots, the additional permission VM.Snapshot is required. Without this permission, snapshot deletion will fail.

The following commands create a dedicated role, user, and assign the required permissions globally:

pveum role add proxsnap --privs VM.Audit,VM.Snapshot
pveum user add proxsnap@pve --password <password>
pveum acl modify / --roles proxsnap --users proxsnap@pve

After creating the user, an API token should be generated. It is recommended to disable privilege separation for this token, as the permissions are already tightly scoped via the assigned role:

pveum user token add proxsnap@pve proxsnap --privsep 0

Ensure that the token is generated for the correct user and role combination used by ProxSnap in your environment. The resulting token ID and secret must be stored securely and configured in ProxSnap.

Using ProxSnap in Proxmox VE Environments

ProxSnap is built with a strong focus on transparency and ease of use. Its output is intentionally structured and explicit, allowing administrators to quickly understand the snapshot state of an entire Proxmox VE cluster without having to interpret complex or condensed information. Every command is designed to provide clear results that can be acted upon immediately.

At its core, ProxSnap operates by querying the Proxmox VE API and collecting snapshot information across all nodes in a cluster. This includes both virtual machines and containers. The tool aggregates this data and presents it in a readable, node based structure, making it easy to spot patterns, inconsistencies, or outdated snapshots.

Cluster Wide Snapshot Overview

The most common entry point when working with ProxSnap is the list mode. By using the -l or --list option, ProxSnap retrieves a complete overview of all nodes in the cluster and lists every VM and container along with their snapshot status. This mode is ideal for regular audits and quick health checks.

The output is grouped by node and clearly distinguishes between guests with and without snapshots. For guests that do have snapshots, ProxSnap prints each snapshot name together with its creation timestamp and a human readable age.

$ proxsnap -l
Node: virt01-de-ne01
 ✓ VM 101 (pmx01-dev.int.gyptazy.com) has no snapshots
 ⚠ VM 110 (dev-sylve03) has 1 snapshots:
 • init (2026-01-01 16:33:35 (2 weeks ago))
 ✓ VM 104 (dev-pmx03) has no snapshots
 ⚠ VM 108 (dev-sylve01) has 1 snapshots:
 • init (2026-01-01 16:33:24 (2 weeks ago))
 ⚠ VM 102 (dev-pmx01) has 1 snapshots:
 • network (2026-01-16 12:22:42 (a day ago))
 ✓ VM 103 (dev-pmx02) has no snapshots
 ⚠ VM 109 (dev-sylve02) has 1 snapshots:
 • init (2026-01-01 16:33:29 (2 weeks ago))
Node: virt02-de-ne01
 ✓ VM 111 (dev-proxmox01) has no snapshots
 ✓ VM 106 (dev-talos02) has no snapshots
 ✓ VM 107 (dev-talos03) has no snapshots
 ✓ VM 105 (dev-talos01) has no snapshots

A checkmark indicates that a guest currently has no snapshots attached, while a warning symbol highlights guests with existing snapshots. This visual distinction makes it easy to focus on systems that may require attention. The combination of exact timestamps and relative ages helps quickly assess whether snapshots are still relevant or potentially outdated.

Finding Snapshots Older Than a Specific Date

For more targeted analysis, ProxSnap provides a date based mode. By supplying the -d or --date option followed by a date in the format YYYY-MM-DD, ProxSnap searches the entire cluster for snapshots that were created before the given date. In other words, it identifies snapshots that are older than the specified cutoff.

This mode is particularly useful after maintenance tasks, migrations, upgrades, or testing phases, where snapshots are often created temporarily and later forgotten. Instead of manually checking each VM or container, ProxSnap highlights all matching snapshots in a single run.

$ proxsnap -d 2026-01-04
Checking for snapshots older than 2026-01-04
⚠ VM 110 (dev-sylve03) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
⚠ VM 109 (dev-sylve02) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
⚠ VM 108 (dev-sylve01) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)

By default, this mode performs a dry run. No changes are made to the environment. ProxSnap simply reports which snapshots match the criteria, allowing you to review the results carefully before deciding on further action.

Removing Outdated Snapshots

Once you have reviewed the output and confirmed that the listed snapshots are no longer needed, ProxSnap can be instructed to remove them automatically. This is done by adding the -r or --remove option. When enabled, ProxSnap deletes the matching snapshots using the Proxmox VE API.

Removal is explicit and controlled. Only snapshots that match the cutoff date are affected, and the implicit current snapshot is never touched.

$ proxsnap -d 2026-01-04 -r
Checking for snapshots older than 2026-01-04 (REMOVING)
⚠ VM 109 (dev-sylve02) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
 → deleted snapshot 'init' of VM 109
⚠ VM 110 (dev-sylve03) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
 → deleted snapshot 'init' of VM 110
⚠ VM 108 (dev-sylve01) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
 → deleted snapshot 'init' of VM 108

Each deletion is logged in detail, showing exactly which snapshot was removed and from which VM or container. This ensures full traceability and makes it easy to audit the cleanup process.

After completing a cleanup run, the list mode can be executed again to verify the result and confirm that the snapshots have been removed successfully.

$ proxsnap -l
Node: virt01-de-ne01
 ✓ VM 101 (pmx01-dev.int.gyptazy.com) has no snapshots
 ✓ VM 110 (dev-sylve03) has no snapshots
 ✓ VM 103 (dev-pmx02) has no snapshots
 ✓ VM 108 (dev-sylve01) has no snapshots
 ✓ VM 109 (dev-sylve02) has no snapshots
 ✓ VM 104 (dev-pmx03) has no snapshots
 ⚠ VM 102 (dev-pmx01) has 1 snapshots:
 • network (2026-01-16 12:22:42 (a day ago))
Node: virt02-de-ne01
 ✓ VM 106 (dev-talos02) has no snapshots
 ✓ VM 107 (dev-talos03) has no snapshots
 ✓ VM 111 (dev-proxmox01) has no snapshots
 ✓ VM 105 (dev-talos01) has no snapshots

This structured workflow makes ProxSnap suitable for both routine snapshot audits and controlled cleanup operations. Administrators can start with a read only overview, narrow the scope using a date threshold, and only enable removal once they fully understand which snapshots will be affected. As a result, snapshot management becomes predictable, safe, and easy to integrate into everyday Proxmox VE operations.

Scenarios of ProxSnap Usage

ProxSnap is designed to address real world operational gaps that commonly appear in Proxmox VE clusters over time. Snapshots are often created with good intentions, but without a clear overview or regular cleanup process, they can easily become forgotten. The following scenarios highlight typical situations where ProxSnap provides immediate value.

• Self managed environments with multiple users
  In environments where developers or operators are allowed to manage their own VMs or containers, snapshots are frequently created before changes, updates, or experiments. Over time, these snapshots are often forgotten once the original task is completed. ProxSnap helps administrators regain visibility across the entire cluster and identify snapshots that no longer serve a purpose.
• Post maintenance and upgrade cleanups
  Snapshots are commonly used as a safety net before system upgrades, migrations, or configuration changes. After a successful maintenance window, these snapshots are rarely revisited. ProxSnap makes it easy to find snapshots that were created before a specific date, allowing teams to clean up old maintenance snapshots in a controlled and predictable way.
• Long running clusters with growing storage pressure
  In clusters that have been running for months or years, snapshot sprawl can quietly consume significant amounts of storage. This often goes unnoticed until storage limits are reached or performance degrades. ProxSnap provides a cluster wide overview that helps identify snapshot heavy guests early and supports regular cleanup as part of ongoing cluster housekeeping.

In all of these scenarios, ProxSnap acts as a visibility and control layer that is missing from default Proxmox VE tooling. Instead of relying on manual checks or assumptions, administrators gain concrete data that can be reviewed, audited, and acted upon. Whether used interactively for troubleshooting or automated as part of regular maintenance, ProxSnap helps ensure that snapshots remain a useful safety feature rather than a hidden operational risk.

Support & Contribution Policy

ProxSnap is provided as-is. There is no official support channel, issue tracking, or roadmap for feature requests at this time. The project is shared primarily as a practical utility for Proxmox VE environments and for transparency into its implementation.

While bug reports and feature requests cannot be accepted via issues, contributions in the form of pull requests are welcome. Submitted changes should be focused, well-tested, and aligned with the existing scope and design of the project. Please note that acceptance and review of contributions are performed on a best-effort basis and without guaranteed response times.

Open-Source & Code of ProxSnap

ProxSnap is developed with an open source mindset, focusing on transparency, reliability, and practical value for Proxmox VE environments. At the current stage, ProxSnap is distributed as prebuilt binary packages, allowing users to benefit from the tool without having to compile or maintain the source code themselves.

The source code of ProxSnap is now publicly available for transparency and review purposes and can be found on GitHub. The publication of the source code is intended to provide insight into the implementation and build trust in the project, rather than to establish a fully community-driven development model at this time.

Please note that issue tracking and feature requests are intentionally disabled for this repository. Publishing source code often comes with expectations around long-term maintenance, rapid bug fixes, feature discussions, and community support. With several other active projects such as ProxLB, ProxCLMC, BoxyBSD, and additional tooling already requiring ongoing attention, available time remains a limiting factor.

That said, contributions are still welcome in the form of pull requests. If you would like to improve ProxSnap, fix issues you encounter, or enhance existing functionality, you are free to do so by submitting a PR.

Even in its current form, ProxSnap already delivers clear value by closing an important operational gap in Proxmox VE cluster management. Making both the binary and the source available allows users to benefit from its functionality today, while maintaining realistic expectations around support and ongoing development.

This approach is not set in stone. As the project evolves and circumstances change, ProxSnap may eventually follow the same path as other projects once sufficient capacity for long-term maintenance and community engagement becomes available.

For now, the focus remains on providing a stable, useful, and well-integrated tool that helps administrators manage snapshots more effectively in real-world Proxmox VE environments. You can also find more background information in this blog post about ProxSnap and automated snapshot cleanups for Proxmox clusters.