Documentation

Getting Started

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

v0.9.12

Contents

  1. About BorgMate
  2. Installation
  3. Adding a Repository
  4. Backups
  5. Browsing and Restoring
  6. Settings & Maintenance

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 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) shows live progress in the detail panel.
  • 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, and check integrity are single button clicks from the repository toolbar. Operations run in a background queue.

AI-assisted development

BorgMate is developed with the help of AI coding assistants. All generated code is manually reviewed, tested, and maintained by the developer. AI is a tool in the workflow, not a substitute for understanding.

Questions or feedback? Contact us at contact@oddbit.io.

2. Installation

Install BorgBackup

brew install borgbackup

Install BorgMate

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

⚠ BorgMate is not yet notarized by Apple, so macOS Gatekeeper may block it on first launch. We hope to fix this in a future release. To allow it, run this command in Terminal after installing:

xattr -cr /Applications/BorgMate.app

Install BorgBackup and dependencies

sudo apt update && sudo apt upgrade -y && sudo apt install -y borgbackup libsecret-tools openssh-client
sudo dnf install borgbackup libsecret openssh-clients
sudo pacman -S borg libsecret openssh

libsecret is used to store passphrases securely in the system keyring. Without it, BorgMate will prompt for the passphrase on every operation.

Install BorgMate

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:

sudo apt install libfuse2
sudo dnf install fuse-libs
sudo pacman -S fuse2

Alternatively, you can extract and run without FUSE:

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

Install WSL and BorgBackup

BorgMate on Windows runs borg commands through WSL (Windows Subsystem for Linux). Open PowerShell as Administrator and run:

wsl --install

Reboot your computer after installation. Then install distro:

wsl --install debian

Then open your WSL terminal and install borg:

sudo apt update && sudo apt upgrade -y && sudo apt install -y borgbackup libsecret-tools openssh-client

BorgMate handles WSL integration automatically — path translation, SSH key permissions, and host key management all work out of the box.

Install BorgMate

Download and run the BorgMate-win-Setup.exe installer.

⚠ Windows SmartScreen may show a warning because the installer is not yet code-signed. Click More info then Run anyway to proceed. We hope to fix this in a future release.

BorgMate will auto-detect borg for Borg 1 repositories and borg2 for Borg 2 repositories when they are on your PATH. You can set separate custom binary paths in Settings.

Note: BorgMate supports Borg 1.4.x and experimental Borg 2.0.0b21 or newer beta builds. Enable Borg 2 support in Advanced settings before creating Borg 2 repositories. Borg 2 is still upstream beta/testing software; use Borg 1.4.x for production backups unless you have chosen to test Borg 2.

3. Adding a Repository

Click Create to initialize a new repository, or Open to add an existing one. The repository editor has five tabs:

  • General — repository name, optional archive name prefix (used in generated archive names; the repository name is used when blank), Borg version, location, and encryption mode. Borg 1 repositories support Local or SSH locations. Borg 2 repositories also support raw Borg URLs such as ssh://, sftp://, file://, rest://, rclone:, s3:, and b2:.
  • Source Folders — directories to include in backups.
  • Schedule — manual or scheduled backups (daily, weekly, monthly, every N hours). When scheduled, you can also opt in to run prune after each backup.
  • Prune — retention rules (keep last N archives, plus per-hour/day/week/month/year counts). Enable only the rules you want; at least one rule must be active for prune to run. By default, the repository is compacted automatically after prune to reclaim freed space (toggle off if you prefer to compact manually).
  • Advanced — borg remote path, rate limit.

For SSH field mode, enter host, port, user, repository path, and optional SSH key. For raw Borg URL mode, enter the complete Borg URL. Do not put passwords or secret tokens in repository URLs; BorgMate rejects URLs that would store credentials in config or logs.

Encryption choices are version-specific. Borg 1 keeps the classic borg encryption names. Borg 2 shows the current Borg 2 modes such as repokey-aes-ocb, repokey-chacha20-poly1305, authenticated, authenticated-blake2, none, and keyfile variants.

Passphrases are stored securely in the system keychain (macOS Keychain, Windows Credential Manager, or Linux libsecret).

4. Backups

Select a repository and click Backup. Progress (percentage, ETA, elapsed time) is shown in the detail panel with a cancel button. Completed operations appear in the Notifications page (bell icon in the sidebar) and trigger native OS notifications.

Scheduled Backups

Configure automatic backups in the Schedule tab of the repository editor. The app must be running (in the system tray) for scheduled backups to trigger. By default, missed backups run automatically on startup.

5. Browsing and Restoring

Select a repository to see its archives in the right panel. Use Restore To... to extract an entire archive, or Browse to open the file tree and restore selected files. The browse dialog supports Show Changes to highlight added and modified files compared to the previous archive. Archives can be deleted individually.

6. Settings & Maintenance

Open Settings from the gear icon at the bottom of the sidebar.

General

  • Language and Theme — interface language (English / Russian / system) and Light / Dark / system appearance.
  • Startup — Start at Login, Start Minimized.
  • Notifications — Check for Updates on startup, Show OS notifications when operations finish.

Data

  • Auto-load — toggle the implicit fetches that run when you select a repository or archive: archive list, repository details (size / chunks), and per-archive details (size / file count). Turning these off keeps the panel empty and shows a Refresh button — useful for slow remotes.
  • Journal — enable or disable journal retention and choose how long to keep operation history.
  • Restore — default extraction options for restored files: skip flags, ACLs, xattrs, or create sparse files.
  • Display — show file sizes with binary units.

Advanced

  • Borg Path Override — override the auto-detected Borg 1 executable. Enable experimental Borg 2 support to show the separate Borg 2 path.
  • SSH Keep-Alive — interval and max retries for detecting dead SSH connections. Set interval to 0 to disable.
  • Logging — write command logs to disk.
  • Log Level — verbosity of the log file: Debug, Info (default), Warning, or Error.
  • Retention Period — how long to keep debug log files.

Repository Maintenance

The More dropdown in the repository toolbar provides:

  • Compact — reclaims unused space in the repository.
  • Check — verifies repository integrity and reports any issues.
  • Prune — applies the retention rules configured in the Prune tab of the repository editor (disabled when no rules are set).
  • Change Passphrase — rotates the repository's encryption passphrase. Enter the new passphrase twice; BorgMate updates the OS keychain entry alongside borg. Disabled for unencrypted repositories.
  • Duplicate — clones the repository entry in BorgMate with a new name (does not duplicate the on-disk data).
  • Remove — removes the repository from BorgMate (does not delete the actual borg repository on disk).