Cloud-PBS TUI: a terminal client to back up your Linux hosts

Backing up a Linux host to a Proxmox Backup Server goes through the official proxmox-backup-client. It is a thorough, reliable tool, but entirely command-line driven: you need to know the target repository, the datastore, the namespace, supply an API token, assemble the right paths, handle encryption and schedule the runs. For occasional use, or when standardising across a fleet, the margin for error is real.

We built Cloud-PBS TUI to address that: a text-mode interface that guides those steps, without hiding anything proxmox-backup-client does underneath. Here is a factual look at the tool and where it stands.

What it is, and what it is not

Cloud-PBS TUI is a terminal application (a TUI, terminal user interface) written in Go. It runs straight in a console, with no graphical server, which makes it usable on a workstation as well as on a server over SSH.

One key point: the tool does not embed the code of proxmox-backup-client. It invokes it as a subprocess. The official client must therefore be installed separately on the host. Cloud-PBS TUI does not reimplement backup: it builds the commands, runs them and surfaces their output. The backup logic stays Proxmox’s own.

The binary is compiled statically (CGO_ENABLED=0), with no external dependency, to stay portable across Linux distributions.

The screens

The interface is organised into five screens, reachable with keys 1 to 5.

Home. A summary view of the current configuration: PBS target, selected sources, active schedule.

Target. The connection form for the Proxmox Backup Server: repository address, datastore, namespace and API token. Fields are validated before being saved.

Sources. The selection of paths to include in the backup. You browse the filesystem tree to add or remove directories, with an estimate of the volume involved.

Schedule. Recurring backup scheduling. The screen generates the matching systemd units (.service and .timer) from presets: hourly, daily at 02:00 or 23:00, weekly, monthly, or a custom OnCalendar expression.

Backups. Browsing the snapshots present in the datastore, and restoring them. Token permissions are tested along the way: a token limited to Datastore.Backup can write backups without necessarily being allowed to read them. The screen flags this rather than failing without explanation.

Running a backup happens from a dedicated panel that streams the logs in real time, while proxmox-backup-client processes the sources.

Encryption

Cloud-PBS TUI can generate a client-side encryption key, via proxmox-backup-client key create. The backup is then encrypted before it leaves the host.

The key is generated without a passphrase (--kdf none): the secret lives only in the key file, whose confidentiality relies on filesystem permissions. The tool never overwrites an existing key, to avoid making backups unreadable by accident.

Configuration

Configuration is stored locally, in the standard XDG directories (~/.config/cloudpbs-tui for configuration, ~/.local/state/cloudpbs-tui for logs). The API token is treated as a secret. Configuration is read back at startup: you find your target, your sources and your schedule from one session to the next.

Where the project stands

Development progresses in milestones. As of today:

• target, sources and schedule configuration is complete;
• backup execution with real-time logs works;
• client-side encryption is in place;
• browsing and restoring snapshots is available;
• a continuous integration pipeline builds and publishes the Linux binaries (amd64 and arm64) on every release.

Three versions have been published, the latest being v0.3.0.

Still to come: .deb packaging for installation through apt, and opening up the source code once the licence is finalised. The tool is under active development.

Download

The binary is built and published with every release. The links below always point to the latest version:

• Linux amd64
• Linux arm64
• SHA256SUMS — SHA256 checksums

After downloading, verify the archive then extract it:

sha256sum -c SHA256SUMS
tar xzf cloudpbs-tui-linux-amd64.tar.gz
./cloudpbs-tui

Reminder: proxmox-backup-client must be installed separately on the host to run an actual backup.

Who it is for

Cloud-PBS TUI is aimed at administrators backing up Linux hosts to a Proxmox Backup Server, whether a managed Cloud-PBS instance or a self-hosted PBS. It is a component of our Cloud-PBS ecosystem, built first for our own use, and which we are opening up gradually.

Running a Linux fleet where backups to PBS take more of your time than they should? Let’s talk.