ProxSave: backing up the Proxmox host itself

The gap ProxSave fills: the node, not the workloads

A working recovery plan needs both your workloads and the configuration of the server that runs them. That sentence from the README is the whole pitch. After a fresh installation there may be network bridges, storage definitions, users, permissions, firewall rules and backup jobs to recreate before your environment is usable again, and that list is longer than most people expect until they need it.

ProxSave is a free, open-source tool for online backups of host configuration on Proxmox Virtual Environment and Proxmox Backup Server. It supports configuration restore and disaster recovery after a server failure, a Proxmox reinstall, or a move to new hardware.

The critical operational property is that configuration backups run without shutting down the host, virtual machines or LXC containers. The host and its workloads remain online during collection. On a virtualization host that is the difference between a tool you can schedule and a tool you can only run during a maintenance window.

The use cases the README lists are concrete rather than hypothetical: recovering a Proxmox VE node after a boot disk or hardware failure, rebuilding the configuration of a Proxmox Backup Server, preparing for a reinstall or migration to replacement hardware, restoring selected settings after an unwanted configuration change, and preserving the configuration of standalone nodes, cluster members and hosts running both PVE and PBS.

What makes this different from a backup tool you already have is scope. ProxSave complements PBS and vzdump backups of virtual machines and containers. It captures VM and LXC configuration, but does not create backups of their running disks or filesystems. It can also collect existing PVE backup files when enabled, but those files still need to be created by your normal guest backup jobs, and PBS datastore contents need their own protection as well.

The project is written in Go and released under the MIT licence. It is an independent project with no affiliation to Proxmox and no paid feature tier.

Detecting the host's role, and what the collectors reach

ProxSave detects the host's PVE and PBS roles and collects the relevant configuration alongside common Linux system settings. On a host running both products, it collects both roles in one backup run, and an optional host-backup mode supports collection from a host filesystem mounted read-only inside a suitably configured LXC appliance.

That detection is what makes a single tool usable across a mixed estate. You are not asked to declare in advance that this node is a PVE server or a backup server, and you are not asked to run a different command for each.

The coverage table is the part to read carefully, because it is the real scope of the tool. For Proxmox VE it collects VM and LXC configuration, storage and datacenter settings, backup jobs, replication settings, users and permissions, firewall rules, HA and SDN configuration, PCI and USB resource mappings, and the Corosync and cluster database at `/var/lib/pve-cluster/config.db`. For Proxmox Backup Server it collects datastore definitions, S3 endpoint settings, remotes, sync, prune and verification jobs, users and access control, notifications, node settings, ACME configuration and tape configuration including tape encryption keys.

Beyond the Proxmox layer it reaches the operating system underneath: interface configuration, bridges, bonds, hostname and DNS settings, mount configuration, ZFS configuration and pool inventory, LVM metadata, iSCSI, multipath, software RAID, encrypted-volume settings and automount configuration, SSH configuration and keys, TLS certificates, system accounts, service definitions, cron jobs, package sources, kernel settings and boot parameters, and local scripts with the root and user home directories.

There is a caveat in the README that should temper expectations: coverage depends on the host's role, the available files and the enabled collectors, and some captured information is provided for reference or manual review rather than applied automatically during restore. That last clause is the important one. Some of what is collected is evidence, not a restore instruction.

Four destinations, and the one that is really different

A backup run creates a local archive. It can also save secondary and cloud copies and create a separate native PBS snapshot, so you can keep recovery data outside the host being protected.

The destinations divide into four kinds. Local storage is a ProxSave archive on a local filesystem path. Secondary storage is another archive copy on a mounted filesystem, such as an NFS or SMB share, NAS, external drive or second disk. Cloud and remote storage covers archive copies through rclone, including S3-compatible storage, Backblaze B2, Google Drive, OneDrive and other supported backends. The fourth is Proxmox Backup Server, described as a native host snapshot of the collected files, sent directly to a PBS storage configured in Proxmox VE.

The native PBS route is the interesting one, because it works differently rather than just adding another copy target. Native PBS uploads require a PVE host, an enabled PBS storage in `/etc/pve/storage.cfg` and `proxmox-backup-client`. ProxSave reads that storage's connection details, datastore, namespace, credentials and encryption key from the PVE configuration and sends the collected file tree directly to PBS. The configured namespace, if used, must already exist.

What you get is a native PBS file backup, with PBS deduplication and incremental transfer of chunks. Each host has its own `host/proxsave-<hostname>` backup group containing a `proxsave.pxar` file archive. ProxSave checks that the uploaded snapshot exists and has the expected encryption mode, manages retention for that group, and attaches the run log to the snapshot.

The reason this is more than a copy target is that a native PBS snapshot is a first class object in the PBS world. It deduplicates, it increments, it has its own retention, and it can be read with the standard PBS tooling. The archive copies are ProxSave's own format, and their restore path is ProxSave's own tooling.

One asymmetry to keep in mind is encryption. PBS encryption follows the key configured on the selected PVE storage and is separate from the age encryption used for ProxSave archive copies. A storage without an encryption key receives unencrypted snapshots.

The restore workflow and the gap in the restore selector

ProxSave provides an interactive restore workflow with four choices: full configuration, storage, base system, or custom categories. You can recover a broad set of settings, or focus on a specific area such as networking, storage definitions or backup jobs.

The category-based restore is the part that makes this practical for a real recovery, because a full restore of a configuration set collected on a node that has since changed is not always what you want. Restoring only the storage definitions, or only the networking, is a much more survivable operation on a host that is still partly working.

The README then notes a limit that is easy to read past: recovery from native PBS snapshots uses PBS tools, and ProxSave's built-in restore selector currently discovers its archive backups in local, secondary and rclone storage. So the guided selector covers the ProxSave archives, and the PBS snapshots are restored with the PBS tooling rather than through the same menu. If you have been relying on the ProxSave interface as your single restore path, that is the thing to know before an incident.

The two encryption schemes interact here too. An archive copy in local, secondary or rclone storage is protected by age encryption and is read back by ProxSave. A native PBS snapshot is protected by the PBS storage's key and is read back by PBS tools. The two are not interchangeable, so a restore plan has to name which kind of backup it is using.

The documentation set referenced from the README is where the operational detail lives, with `docs/CONFIGURATION.md` carrying the PBS storage reference and `docs/CLOUD_STORAGE.md` the cloud storage details, alongside a `docs/README.md` index and the project site at proxsave.dev.

Building the tool from Go source

The README does not give a one line install command, so the source tree is the route in, and it is a conventional Go layout. The module is `github.com/tis24dev/proxsave` and the module file declares `go 1.26.9`. The repository has `cmd/` for the command entry point, `internal/` for the implementation, `pkg/` for the exported packages, `docs/` for the documentation, plus `embed.go`, `go.mod`, `go.sum`, a `Makefile`, a `NOTICE` file, an `install.sh` and an `upgrade-beta.sh`.

The Makefile shows how the binary is produced. The `build` target derives the version from `git describe`, using the exact tag when the working tree is clean and a dirty or dev suffix otherwise, then passes the version, the commit hash, the build timestamp and the support email into the build with `go build -ldflags`, writing the result to `build/proxsave` from `./cmd/proxsave`. The version is injected into `internal/version`.

The tooling is standard and modern. The dependencies include `filippo.io/age` for the age encryption used on archive copies, `charm.land/bubbletea/v2` with `bubbles` and `lipgloss` for the interactive terminal interface, `github.com/Masterminds/semver/v3` for version comparison, `golang.org/x/crypto` for the SSH and cryptographic work, and `golang.org/x/term` and `golang.org/x/text` for terminal and text handling.

The presence of the Bubble Tea stack is the clearest signal about the intended shape of the tool. The restore workflow described in the README as interactive, with four choices, is a terminal user interface rather than a series of command line flags, and the colour profile handling in the dependency list is there so that the interface renders correctly in a terminal with limited colour support.

The repository also carries a `codecov.yml`, a `.golangci.yml` configuration, a `.coderabbit.yaml`, a `CONTRIBUTING.md` and a `githooks/` directory, and the Makefile has a coverage target with a threshold of 50.0 that a separate `coverage-check` target can enforce.

Where ProxSave is the wrong tool

The most important limitation is the one the README puts in the first paragraph of the coverage discussion, and it is worth stating in your own words before anything else: ProxSave does not create backups of running disks or filesystems. It captures VM and LXC configuration. If your guests hold data, they need your normal guest backup jobs, and ProxSave does not replace them. The README says it can also collect existing PVE backup files when enabled, but those files still need to be created by your normal guest backup jobs, and PBS datastore contents need their own protection as well.

The second limitation is that a configuration backup is not a restore plan on its own. Some captured information is provided for reference or manual review rather than applied automatically during restore, and the coverage of collectors depends on the host's role and the files that exist on it. A host rebuilt from scratch may not have the same files, the same storage definitions or the same cluster state, and a restore that assumes the original environment will not be perfectly applicable.

The third is scope of the platform. This is a Proxmox tool. It knows about PVE and PBS, and while it collects common Linux system settings alongside, it is not a general Linux host configuration backup. And it is a Go program, so it needs a Go toolchain or a released binary, and the README's own summary of the problem mentions that a reinstall leaves backup jobs to recreate, which is exactly the kind of thing you are trying to avoid, so a tool that can restore a host is also a tool that has to be re-installed on the rebuilt host.

The alternative approach, and it is a real one, is to treat the host configuration as a file repository and version it. Proxmox's own configuration is largely text under `/etc/pve`, and many operators already keep those files in Git and rebuild a node from a template. That approach gives you history and review for free, but it does not collect the operating system layer, does not cover the PBS configuration, does not produce an archive, and does not survive a disk failure on the node that held the clone. The difference in approach is direct: version control gives you the files that are already configuration, ProxSave gives you a collected, restorable archive of the whole configuration surface including the parts you were not versioning.

Editorial conclusion

Adopt ProxSave if you run Proxmox and your recovery plan covers the guests but not the host, because a fresh install has bridges, storage definitions, users, firewall rules and backup jobs to recreate before anything is usable again. Do not adopt it as a replacement for PBS or vzdump, since it captures VM and LXC configuration without creating backups of their running disks or filesystems. Before you rely on it, read `docs/CONFIGURATION.md` for the PBS storage section and check that the storage you point it at has an encryption key, since a storage without one receives unencrypted snapshots, and confirm your guests still have their own backup job, because ProxSave does not create those.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tis24dev/proxsave on GitHub