Documentation

Getting Started

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

v0.9.9

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 install 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

This installs WSL 2 with Ubuntu by default. Restart your computer when prompted. If you prefer Debian:

wsl --install -d Debian

Then open your WSL terminal and install borg:

sudo apt update && sudo apt install borgbackup

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 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.

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), location (Local or SSH), encryption mode. For SSH repos: host, port, user, path, and SSH key. Passphrase-protected keys are supported.
  • 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.

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.
  • Updates & Notifications — Check for Updates on startup, Show OS notifications when operations finish.
  • 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.
  • Notification Retention — how long to keep notification records.

Advanced

  • Borg Binary Path — override the auto-detected borg location.
  • Enable Debug Logging — write detailed 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.
  • SSH Keep-Alive — interval and max retries for detecting dead SSH connections. Set interval to 0 to disable.
  • Developer Mode — enables the Debug page showing background operations with real-time output. Session-only.

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).