If you've already set up Proxmox Backup Server to protect your VMs and containers, you've probably had this thought: "why can't I back up my other stuff here too?" Your NAS. That old Ubuntu box running Pi-hole on bare metal. Your laptop's home folder. None of those are Proxmox VE guests, so the usual backup jobs in the Proxmox VE web interface don't touch them at all.
Turns out you don't need them to be. Proxmox ships a standalone command-line client that runs on pretty much any Debian-based Linux machine, and it talks to your existing PBS datastore the same way a VM backup job does - deduplicated, incremental, and encrypted if you want it to be. This guide walks through installing it, connecting it to your datastore, and running your first backup and restore.
I'll assume you already have a working Proxmox Backup Server instance somewhere on your network. If you haven't set that up yet, do that first - this article is specifically about backing up machines that aren't Proxmox VE hosts.
What You Will Learn
- What the Proxmox Backup Client actually is and how it's different from a normal Proxmox VE backup job
- How to add the client-only APT repository to a Debian or Ubuntu machine
- How to create an API token so you're not typing your PBS password into scripts
- How to run your first file-level backup and see it show up in the PBS web interface
- How to list snapshots and restore individual files
- The errors people actually hit the first time, and what they mean
What Is This Feature?
The Proxmox Backup Client is the same tool your Proxmox VE host uses internally to send VM and container backups to PBS - Proxmox just also ships it as a standalone package you can install anywhere. It comes in two flavors. proxmox-backup-client is a normal Debian package with its dependencies pulled in by APT, and it's what you want for any Debian or Ubuntu system. proxmox-backup-client-static is a statically linked binary with no dependencies at all - you can copy that one onto pretty much any x86-64 Linux system, Debian-based or not, and it'll just run.
Once it's installed, the client reads a directory (or a raw block device) and packs it into a pxar archive - Proxmox's own archive format, similar in spirit to tar but built so that individual files can be deduplicated at the chunk level. That archive gets streamed straight to your PBS datastore over an encrypted connection. PBS stores it as a snapshot you can browse, mount, or restore from later, exactly like a VM backup.
If you've never used PBS before: a datastore is just a chunk store on disk where PBS keeps deduplicated backup data. Every backup client, whether it's a Proxmox VE host or your laptop, writes into the same pool of chunks, so if two machines happen to store the same file, PBS only keeps one copy of it on disk.
Why Would You Use It?
The honest answer is deduplication and retention, in one place. If you're currently backing up your NAS with rsync to a spare drive, or your laptop with some cloud sync tool, you get none of PBS's chunk-based dedup and none of its retention rules (keep-daily, keep-weekly, and so on) applied automatically. Point that same laptop at your PBS datastore instead, and every backup after the first one only has to upload the blocks that actually changed.
There's also a practical case for anyone running a "hybrid" homelab - a Proxmox VE cluster plus a couple of standalone boxes that never got virtualized (an old media server, a Raspberry Pi, a work laptop). Instead of maintaining two or three different backup tools, you get one datastore, one retention policy, and one place to check when you're wondering "did last night's backup actually run?"
I'll be upfront about the downside too: this only backs up files and directories, not a full bare-metal image with partition table and bootloader. If your goal is "restore this exact machine onto new hardware in ten minutes," a pxar backup of / gets you your data and configs back, but you're still reinstalling the OS first. For that use case, pair it with your distro's normal reinstall process, then restore files on top.
Prerequisites
- A working Proxmox Backup Server with at least one datastore already created
- A Debian or Ubuntu machine you want to back up (Debian 11/12/13 or Ubuntu 20.04 and newer all work)
- Root or sudo access on that machine
- Network access from the client machine to your PBS server on TCP port 8007
- A PBS user account, or better, an API token (we'll create one below)
You do not need Proxmox VE installed on the machine you're backing up. That's the whole point here - this works on a plain Debian box, a Synology running Debian-based DSM add-ons, or a cloud VPS just as well as it does on a homelab server.
Step-by-Step Tutorial
1. Add the Proxmox release key
Download and install Proxmox's signing key so APT can verify the repository. On Debian 12 (Bookworm) or Debian 13 (Trixie):
wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
-O /usr/share/keyrings/proxmox-archive-keyring.gpgIf you're on Trixie, swap in the correct keyring filename for your release from the same directory listing. It's worth double-checking the checksum Proxmox publishes for the keyring rather than trusting a random download blindly - a mismatched hash means something in the chain got tampered with or corrupted.
2. Add the client-only repository
This is the part people get wrong most often: there's a separate, lightweight repository just for the backup client, so you're not pulling in the full Proxmox VE or PBS package set on a machine that isn't running either.
On Debian 13 (Trixie), create /etc/apt/sources.list.d/pbs-client.sources:
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpgOn Debian 12 (Bookworm), create /etc/apt/sources.list.d/pbs-client.list instead:
deb http://download.proxmox.com/debian/pbs-client bookworm mainUbuntu users: since Ubuntu shares Debian's APT stack and glibc, you use the matching Debian codename for your Ubuntu release rather than an Ubuntu-specific one - for example, Ubuntu 20.04 LTS maps to bullseye.
3. Install the package
apt update
apt install proxmox-backup-clientOn a fresh Debian 12 minimal install this pulls down maybe 15-20 MB of packages and takes under a minute. If apt update fails here, it's almost always the repository file or the keyring path - check both before assuming something's broken on Proxmox's end.
Not running Debian or Ubuntu at all - Arch, Alpine, or something more exotic? Grab proxmox-backup-client-static from the same download server instead, drop the binary somewhere on your PATH, and skip the APT steps entirely.
4. Create an API token on the PBS side
You could authenticate with your PBS username and password directly, but an API token is safer - you can revoke it without changing your login password, and you can scope it to exactly the permissions it needs. In the PBS web interface, go to Configuration > Access Control > API Token, pick a user (or create a dedicated backup user first), give the token a name like backup, and save the secret it shows you - it's only displayed once.
Then grant that token DatastoreBackup permission on the specific datastore path, under Permissions in the same section. Skipping this step is the single most common reason a first backup fails with a permission error.
5. Run your first backup
Back on the client machine, set the repository and run a backup of, say, your home directory:
proxmox-backup-client backup home.pxar:/home \
--repository backup-user@pbs!backup@pbs.example.lan:mydatastoreRemember to quote the auth-id if your shell treats ! as special - some shells do, some don't, and it's an easy way to lose an afternoon to a confusing error. You'll be prompted for the token secret unless you've exported it as PBS_PASSWORD first, and if PBS is running with a self-signed certificate, set PBS_FINGERPRINT to the fingerprint shown on the datastore's dashboard so the client trusts it without you having to add a real CA cert.
A 10 GB home directory with the usual mix of documents and photos typically takes two to five minutes over gigabit LAN on the first run. Every backup after that only uploads changed chunks, so a second run of the same directory an hour later might finish in a few seconds.
6. Confirm it landed in PBS
Open the PBS web interface, click into your datastore, and you should see a new backup group under the host name of the client machine, with one snapshot inside it timestamped to when you ran the command. That's your proof it worked - don't just trust a clean exit code, actually go look.
Commands Explained
| Command | What it does |
|---|---|
proxmox-backup-client backup home.pxar:/home --repository ... | Archives /home into a pxar file named home.pxar and uploads it as a new snapshot to the given repository (server + datastore). |
proxmox-backup-client snapshot list | Lists every snapshot the client can see in the configured repository, along with size and file counts. |
proxmox-backup-client restore <snapshot> home.pxar /restore/path | Pulls one archive out of a specific snapshot and extracts it to a local directory. |
proxmox-backup-client catalog shell <snapshot> home.pxar | Opens an interactive shell inside the archive so you can browse it and pull out individual files without restoring the whole thing. |
The --repository flag follows the pattern [[username@]server[:port]:]datastore. Leave off the username and server and it defaults to root@pam on localhost:8007 - useful only if you're running the client on the PBS box itself, which isn't the scenario here. In practice you'll almost always write out the full form: user@realm@host:datastore, or with an API token, user@realm!tokenname@host:datastore.
Common Errors
Error: unable to open chunk store... permission denied nearly always means the API token doesn't have DatastoreBackup permission on that datastore path yet, or you granted it on the wrong path. Double-check the permission's path matches the datastore name exactly.
certificate verification failed shows up when PBS is using its default self-signed certificate and you haven't set PBS_FINGERPRINT. Grab the fingerprint from the datastore summary page in the PBS interface and export it before running the backup.
Connection refused or a long timeout usually means a firewall between the two machines is blocking TCP 8007, not that PBS is down. Test with a quick curl -k https://pbs-host:8007 from the client first.
If apt update complains about a missing or invalid signature after step 1, the keyring filename you downloaded probably doesn't match the release codename in your sources file - trixie keys won't validate a bookworm-suite repo entry, for instance.
Troubleshooting
Start by isolating which side has the problem. Run proxmox-backup-client snapshot list --repository ... with no backup involved - if that fails, it's an auth or network issue, not anything to do with the files you're trying to back up.
Slow first backups are normal and not a bug. Every chunk has to be uploaded and hashed the first time; the speedup from deduplication only shows up on the second and later runs of the same source. If a repeat backup of an unchanged directory still takes as long as the first one, something's forcing a full re-read - check that the client and server clocks aren't wildly out of sync, since PBS uses timestamps as part of change detection.
If a restore comes back with files but the permissions or ownership look wrong, that's expected when restoring as a different user than the one the backup was taken from. Run the restore as root, or re-apply ownership afterward with chown -R on the restored path.
Best Practices
Use a dedicated API token per machine rather than one shared token across every client. If a laptop gets stolen, you revoke that one token and nothing else is affected.
Wrap the backup command in a small script and drop it in cron or a systemd timer rather than running it by hand. Something like a nightly 2 a.m. job with a log file you can glance at is enough for most homelabs - you don't need anything fancier than that to start.
Set retention rules on the datastore side (keep-daily, keep-weekly, keep-monthly) rather than letting snapshots accumulate forever. PBS prunes old snapshots automatically once you've configured a prune job, but it won't do it on its own until you set one up.
If the machine you're backing up holds anything sensitive, turn on client-side encryption before your first backup rather than after. Encrypting later means your existing unencrypted snapshots stay unencrypted - it's not retroactive.
Frequently Asked Questions
Do I need Proxmox VE installed to use this?
No. The client only needs network access to a Proxmox Backup Server. The machine you're backing up can be running any Debian-based distro, or nothing Proxmox-related at all if you use the static binary.
Can I back up Windows with this?
Not directly - there's no native Windows build of the client. Some people run it inside WSL to back up specific folders, but that's a workaround, not an officially supported path.
Does this replace a full VM backup for a physical machine?
No. It backs up files and directories, not a bootable disk image. Think of it as protecting your data and configuration, not as bare-metal disaster recovery.
Is the connection to PBS encrypted?
Yes, the client always talks to PBS over TLS. Client-side archive encryption is a separate, optional feature on top of that transport encryption.
What happens if I lose the API token secret?
Just revoke it in the PBS web interface and create a new one. Tokens aren't recoverable once the secret's been shown to you, by design.
Conclusion
Once you've got Proxmox Backup Server running for your VMs and containers anyway, extending it to the handful of non-Proxmox machines on your network costs you about ten minutes per machine and a bit of API token bookkeeping. You end up with one dedup'd datastore, one set of retention rules, and one web interface to check instead of a pile of half-remembered rsync scripts and cloud sync folders you're not totally sure are still running.
Get one machine backing up cleanly first, confirm you can actually restore a file from it, and only then go add it to cron and move on to the next box on your network.