Documentation

Getting Started

Everything you need to set up BorgMate and start backing up your data.

Contents

  1. About BorgMate
  2. Prerequisites
  3. Installation
  4. Adding a Repository
  5. Configuring Source Folders
  6. Running a Backup
  7. Browsing and Restoring
  8. Repository Maintenance
  9. Notifications
  10. SSH Repositories
  11. Windows (WSL)
  12. Settings

1. About BorgMate

BorgMate is a cross-platform desktop application that provides a modern graphical interface for BorgBackup — the deduplicating archiver trusted by sysadmins worldwide. It removes the need to memorize command-line flags and cron configurations while preserving the full power of borg.

Why BorgMate?

  • Native performance — built with .NET and Avalonia UI, delivering a responsive experience without the overhead of Python or Electron.
  • Windows support through WSL — transparently handles path translation, SSH key permissions, and process management across the Windows/WSL boundary.
  • Real-time operation tracking — every operation (backup, restore, compact, check, prune) shows live progress in an activity view.
  • Secure by design — passphrases stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret), never in config files. No telemetry, no analytics, no tracking.
  • One-click operations — backup, compact, check integrity, and prune are single button clicks from the repository toolbar. Operations run in a background queue.

What BorgMate is not

BorgMate is not a backup service. It doesn't host your data, sell you storage, or require an account. It's a local application that talks directly to borg. Your data goes where you tell it to — a local drive, a NAS, a remote server over SSH — and nowhere else.

2. Prerequisites

BorgMate requires the following tools to be installed on your system:

  • BorgBackup 1.4.x — the deduplicating backup engine. BorgMate is a graphical frontend that calls the borg command-line tool under the hood.
  • OpenSSH — required for connecting to remote repositories over SSH. Most systems have it pre-installed; Windows users get it through WSL.
  • libsecret (Linux only) — used to securely store passphrases in the system keyring. Install libsecret-tools (Debian/Ubuntu) or libsecret (Fedora/Arch).

Installing BorgBackup

macOS
brew install borgbackup
Ubuntu / Debian
sudo apt update && sudo apt upgrade -y && sudo apt install borgbackup
Arch Linux
sudo pacman -S borg
Fedora
sudo dnf install borgbackup

BorgMate will auto-detect the borg binary if it's on your PATH. You can also set a custom path in Settings.

Note: BorgMate currently supports borg 1.4.x. Borg 2.x support is planned for a future release.

Installing libsecret (Linux)

BorgMate uses secret-tool (from libsecret) to store passphrases securely in the system keyring. It is not always installed by default.

Ubuntu / Debian
sudo apt install libsecret-tools
Fedora
sudo dnf install libsecret
Arch Linux
sudo pacman -S libsecret

Without libsecret, BorgMate will prompt for the passphrase on every operation instead of storing it.

Installing OpenSSH

SSH is needed if you plan to use remote repositories. It is pre-installed on macOS and most Linux distributions. To verify:

ssh -V

If SSH is not installed:

Ubuntu / Debian
sudo apt install openssh-client
Fedora
sudo dnf install openssh-clients

On Windows, SSH is available inside your WSL distribution (see the WSL section).

3. Installation

macOS

Download the .dmg file for your architecture (Apple Silicon or Intel). Open the DMG and drag BorgMate to your Applications folder.

BorgMate is not notarized by Apple, so macOS Gatekeeper may block it on first launch. To allow it, run this command in Terminal after installing:

xattr -cr /Applications/BorgMate.app

Alternatively, right-click the app in Finder and select Open — macOS will show an option to open it anyway.

Linux

Download the .AppImage file. Make it executable and run:

chmod +x BorgMate.AppImage && ./BorgMate.AppImage

AppImages require FUSE 2. On newer distributions (Debian 13+, Ubuntu 24.04+, Fedora 40+) that ship FUSE 3, you may need to install the compatibility package:

Debian / Ubuntu
sudo apt install libfuse2
Fedora
sudo dnf install fuse-libs
Arch Linux
sudo pacman -S fuse2

Alternatively, you can extract and run without FUSE:

./BorgMate.AppImage --appimage-extract && ./squashfs-root/AppRun

Windows

Download and run the Setup.exe installer. BorgMate on Windows uses WSL (Windows Subsystem for Linux) — see the WSL section below.

4. Adding a Repository

A repository is where borg stores your backups. It can be a local directory or a remote SSH server.

  • Go to the Repositories page (first icon in the sidebar).
  • Click Create to initialize a new repository, or Open to add an existing one.
  • Give it a name and choose between Local or SSH location.
  • For local repositories, select a directory path.
  • For SSH repositories, enter the host, port, user, and path. Optionally set an SSH key.
  • Choose an encryption mode (recommended: repokey-blake2). You'll be prompted for a passphrase.
  • Click Save. BorgMate will initialize the repository.

Your passphrase is stored securely in the system keychain (macOS Keychain, Windows Credential Manager, or Linux libsecret).

5. Configuring Source Folders

Source directories are configured directly on each repository.

  • Select a repository and click Edit.
  • Go to the Source Folders tab.
  • Click Add to browse and select directories to back up.
  • Remove directories by selecting them and clicking Remove.
  • Click Save.

6. Running a Backup

Select a repository and click Backup in the toolbar. Progress is shown in the repository detail panel:

  • A spinner appears on the repository icon while running.
  • The detail panel shows a progress bar with percentage, ETA, file count, and elapsed time.
  • Click the stop button next to the progress bar to cancel.

Completed operations appear in the Notifications page with their result (completed, failed, cancelled). Native OS notifications are sent when operations complete (can be disabled in Settings).

Scheduled Backups

To set up automatic backups:

  • Select a repository and click Edit.
  • Go to the Schedule tab and select Scheduled.
  • Choose a frequency: Daily, Weekly, Monthly, or Every N Hours.
  • Set the time, day of week, or interval as applicable.
  • Click Save.

The repository list shows the schedule and next run time. The Run missed backups on startup checkbox (enabled by default) controls whether past-due backups run automatically when the app starts. When disabled, missed backups are skipped and the next run advances to the next future occurrence. The app must be running (in the system tray) for scheduled backups to trigger.

7. Browsing and Restoring

Select a repository on the Repositories page to see its archives in the right panel.

  • Select an archive to view its size and file count in the detail panel.
  • Restore to... — extracts the entire archive to a directory of your choice.
  • Browse — opens a dialog showing the archive's file tree with checkboxes and file type icons. Narrow directory paths auto-expand for convenience. Use Show Changes to highlight files added (blue) or modified (bold) since the previous archive. Select specific files or directories, then click Restore Selected To... to extract only the selected items.
  • Restore progress (status, percentage, ETA, elapsed time) shows in the archive detail panel with a cancel button.
  • Restore operations are tracked in the Notifications page.
  • Archives can be deleted individually with confirmation.

8. Repository Maintenance

The repository toolbar and More dropdown provide maintenance operations:

  • Compact (toolbar button) — reclaims unused space in the repository.
  • Check (More menu) — verifies repository integrity and reports any issues.
  • Statistics — view repository size, chunk counts, and archive count in the detail panel below the repository list.

All maintenance operations show progress in the repository detail panel. Repository and archive controls are disabled while an operation is running.

9. Notifications

The Notifications page (bell icon in the sidebar) shows completed, failed, and cancelled operations:

  • Each entry shows a status icon (checkmark, error, or stop sign), operation title, relative time, and result.
  • A blue badge on the bell icon shows the number of unread notifications.
  • Use Clear All in the header to remove all entries.

Notification records are persisted to disk and visible across app restarts. Running operation progress is shown in the repository detail panel.

10. SSH Repositories

BorgMate supports remote repositories over SSH. To set up:

  • Ensure you have SSH access to the remote server (key-based authentication recommended).
  • When creating/editing a repository, select SSH as the location type.
  • Enter the host, port, username, and repository path on the remote server.
  • Optionally select your SSH private key file.
  • If your SSH key is passphrase-protected, BorgMate will prompt for it and store it securely.

For advanced setups, you can set a custom Borg Remote Path in the Advanced tab if the borg binary on the server is not in the default location.

11. Windows (WSL)

On Windows, BorgMate runs borg commands through WSL (Windows Subsystem for Linux). Follow these steps to set up WSL with BorgBackup:

Step 1: Install WSL

Open PowerShell as Administrator and run:

PowerShell (Administrator)
wsl --install

This installs WSL 2 with Ubuntu by default. Restart your computer when prompted. On first launch, WSL will ask you to create a Linux username and password.

Step 2: Install Debian (recommended)

If you prefer Debian over Ubuntu, or want a lightweight distribution:

PowerShell
wsl --install -d Debian

To see all available distributions:

wsl --list --online

Step 3: Install BorgBackup inside WSL

Open your WSL terminal and install borg:

WSL (Ubuntu / Debian)
sudo apt update && sudo apt upgrade -y && sudo apt install borgbackup

Verify the installation:

borg --version

How BorgMate uses WSL

BorgMate handles the WSL integration automatically:

  • Windows paths are translated to WSL mount points (e.g., C:\Users becomes /mnt/c/Users).
  • SSH keys on Windows drives are copied into WSL (~/.ssh/) with correct permissions (chmod 600).
  • Passphrase-protected SSH keys are handled via an inline SSH_ASKPASS script.
  • New SSH host keys are auto-accepted (StrictHostKeyChecking=accept-new).

12. Settings

Open Settings from the gear icon at the bottom of the sidebar. Settings are organized into two tabs:

General

  • Language — English or Russian (or auto-detect from system).
  • Theme — Light, Dark, or follow system preference.
  • Check for Updates — enable or disable automatic update checks on startup.
  • Start at Login — launch BorgMate automatically when you log in.
  • Start Minimized — start in the system tray without showing the window.
  • Notification Retention — how long to keep notification records (one day, one week, one month, one year, or forever).

Advanced

  • Borg Binary Path — override the auto-detected borg location.
  • Enable Debug Logging — write detailed command logs to disk.
  • Log Retention Period — how long to keep debug log files.
  • SSH Keep-Alive — interval (seconds) and max retries for detecting dead SSH connections. Prevents borg from freezing on unstable networks. Set interval to 0 to disable.
  • Developer Mode — enables the Debug page in the sidebar, which shows all background operations with real-time stdout/stderr output and process details. Session-only — resets on app restart.