Skip to content

Windows Agent Setup

Jump to bottom
Marc Pope edited this page Feb 24, 2026 · 4 revisions

Windows Agent Setup

Borg Backup Server for NATIVE Windows Backup Progress

Pre-Release Software: Windows agent support is currently in pre-release and should only be used for testing on non-production workloads. We'd love your feedback — please report issues or share your experience at github.com/marcpope/borgbackupserver/issues.

This guide covers installing and configuring the BBS backup agent on Windows. The agent runs as a Windows Service and includes a bundled Python runtime — no additional software needs to be installed.

Prerequisites

Before installing the agent on your Windows machine, ensure you have:

  • Windows 10 or Windows 11 (64-bit)
  • Administrator access — the installer must be run from an elevated Command Prompt or PowerShell
  • Network access to your BBS server (HTTPS, typically port 443)

The installer will automatically download and install Borg for Windows — no manual setup required.

Step 1: Create a Client in BBS

Before installing the agent, create a client entry in the BBS web interface:

  1. Log in to your BBS server
  2. Navigate to Clients and click Add Client
  3. Enter a name for the Windows machine (e.g., "Office-PC")
  4. Click Create Client
  5. On the client detail page, go to the Install tab and click Windows
  6. Copy the install command — you'll need this in the next step

Step 2: Install the Agent

Open an Administrator Command Prompt or PowerShell window on the Windows machine:

  1. Right-click the Start button and select Terminal (Admin) or Windows PowerShell (Admin)
  2. Paste the install command from Step 1

The command looks like this:

powershell -ExecutionPolicy Bypass -Command "& {iwr -UseBasicParsing 'https://your-server.com/api/agent/download?file=install-windows.ps1' -OutFile $env:TEMP\bbs-install.ps1; & $env:TEMP\bbs-install.ps1 -Server 'https://your-server.com' -Key 'YOUR_API_KEY'}"

The installer will:

  1. Verify connectivity to your BBS server
  2. Download and install Borg for Windows to C:\Program Files\BorgBackup\
  3. Add Borg to the system PATH
  4. Download the agent launcher and script
  5. Install a bundled Python runtime (no system Python needed)
  6. Write the agent configuration
  7. Download the SSH key for secure repository access
  8. Install and start the BorgBackupAgent Windows Service

You should see output similar to:

  ================================================================
    Borg Backup Server - Windows Agent Installer
  ================================================================

  -> Checking server connectivity...
  [OK] Server reachable
  -> Finding latest Borg for Windows release...
  [OK] Latest release: v1.4.4-win5
  -> Downloading v1.4.4-win5...
  [OK] Downloaded borg-windows.zip
  -> Installing Borg to C:\Program Files\BorgBackup...
  [OK] Installed: borg.exe 1.4.4
  -> Adding Borg to system PATH...
  [OK] Added to system PATH
  -> Downloading agent launcher...
  [OK] Downloaded bbs-agent.exe
  -> Downloading agent script...
  [OK] Downloaded bbs-agent-run.py
  [OK] Python already installed: Python 3.11.4
  -> Writing configuration...
  [OK] Config written
  -> Downloading SSH key...
  [OK] SSH key saved
  -> Installing Windows Service...
  [OK] Service 'BorgBackupAgent' installed
  -> Starting service...
  [OK] Service is running

  ================================================================
    Installation Complete!
  ================================================================

Step 3: Verify the Agent is Online

After installation, the agent should appear online in the BBS web interface within 30 seconds. Check the Clients page — the status should change from Setup (blue) to Online (green).

How It Works

Architecture

On Windows, the BBS agent uses a launcher pattern:

  • bbs-agent.exe — A compiled launcher that includes a bundled Python runtime. This is the binary that runs as a Windows Service. It never needs to be updated.
  • bbs-agent-run.py — The actual agent script. When the server pushes an agent update, only this file is replaced and the service is restarted.
  • Borg for Windows — A native Windows build of BorgBackup, downloaded from marcpope/borg-windows. Installed to C:\Program Files\BorgBackup\.

File Locations

Path Description
C:\ProgramData\bbs-agent\bbs-agent.exe Agent launcher (Windows Service binary)
C:\ProgramData\bbs-agent\bbs-agent-run.py Agent script (updated automatically)
C:\ProgramData\bbs-agent\config.ini Agent configuration
C:\ProgramData\bbs-agent\ssh_key SSH private key for borg access
C:\ProgramData\bbs-agent\bbs-agent.log Agent log file
C:\ProgramData\bbs-agent\python\ Bundled Python runtime
C:\Program Files\BorgBackup\borg\borg.exe Borg binary

Archive Path Format

Windows backups store file paths in a portable format using the drive letter as a top-level directory:

C/Users/marcp/Documents/file.txt
D/Projects/myapp/src/main.py

This allows archives to be browsed and extracted correctly on any operating system.

Service Management

Common Commands

Open an Administrator Command Prompt or PowerShell:

# Check service status
sc query BorgBackupAgent

# Stop the agent
Stop-Service BorgBackupAgent

# Start the agent
Start-Service BorgBackupAgent

# Restart the agent
Restart-Service BorgBackupAgent

# View last 50 log lines
Get-Content "C:\ProgramData\bbs-agent\bbs-agent.log" -Tail 50

# Follow the log in real-time
Get-Content "C:\ProgramData\bbs-agent\bbs-agent.log" -Tail 50 -Wait

Configuration

The agent configuration is stored at C:\ProgramData\bbs-agent\config.ini:

[server]
url = https://your-bbs-server.com
api_key = abc123...

After editing the configuration, restart the service:

Restart-Service BorgBackupAgent

Backup Directories

When creating a backup plan for a Windows client, specify directories using Windows path syntax:

C:\Users\marcp
C:\Projects
D:\Data

Each line should contain one directory path. The BBS interface will show Windows-style path hints when it detects a Windows agent.

Restoring Files

Restore to Original Location

When restoring files from a Windows backup without specifying a destination path, BBS automatically handles the drive letter mapping. Files are restored to their original drive location (e.g., C:\Users\marcp\Documents\file.txt).

Note: In-place restore can only target one drive at a time. If your selected files span multiple drives (e.g., files from both C:\ and D:\), BBS will prompt you to either select files from a single drive or specify a custom destination path.

Restore to Custom Path

If you enter a destination path (e.g., C:\Restore), files are extracted there with the full directory structure including the drive letter prefix:

C:\Restore\C\Users\marcp\Documents\file.txt

Download Files

You can also download files directly from the BBS web interface as a .tar.gz archive. This works regardless of the client's operating system.

Upgrading

Agent Updates

The agent script updates automatically when triggered from the BBS dashboard. Go to the client detail page and click Update Agent. The server sends the latest agent script, which replaces bbs-agent-run.py and restarts the service.

Borg Updates

Borg for Windows updates can be triggered from the BBS dashboard. The agent downloads the latest release from GitHub and replaces the installation at C:\Program Files\BorgBackup\.

Reinstalling

To upgrade the installer itself or perform a clean reinstall, simply re-run the install command from Step 2. The installer will:

  1. Stop the existing service
  2. Remove the old Borg installation
  3. Download and install the latest versions
  4. Restart the service

Uninstalling

To completely remove the agent from your Windows machine, run the uninstaller from an Administrator PowerShell:

powershell -ExecutionPolicy Bypass -Command "& {iwr -UseBasicParsing 'https://your-server.com/api/agent/download?file=uninstall-windows.ps1' -OutFile $env:TEMP\bbs-uninstall.ps1; & $env:TEMP\bbs-uninstall.ps1}"

This removes:

  • The BorgBackupAgent Windows Service
  • Agent files in C:\ProgramData\bbs-agent\
  • Borg installation in C:\Program Files\BorgBackup\
  • Borg from the system PATH

Note: The client entry on the BBS server must be removed manually via the web interface.

Troubleshooting

Agent Not Coming Online

Check if the service is running:

sc query BorgBackupAgent

If the service is stopped, start it:

Start-Service BorgBackupAgent

Check the agent log:

Get-Content "C:\ProgramData\bbs-agent\bbs-agent.log" -Tail 50

Look for connection errors, SSL issues, or authentication failures.

Verify network connectivity:

Invoke-WebRequest -Uri "https://your-bbs-server.com" -UseBasicParsing

Backups Failing with "Access Denied"

Some Windows system files and directories are protected and cannot be backed up even with administrator privileges. Common examples include:

  • C:\Users\<user>\AppData\Local\Microsoft\Windows\WebCache\
  • C:\Users\<user>\NTUSER.DAT
  • C:\Users\<user>\AppData\Local\Microsoft\Windows\Notifications\

These permission warnings are normal and do not indicate a failed backup. The backup will complete successfully for all accessible files. You can add exclusion patterns in your backup plan to suppress these warnings.

SSH Key Issues

If the agent log shows SSH key errors:

  1. The SSH key is downloaded automatically on the agent's first connection
  2. If the key is missing or corrupt, restart the service — it will re-download the key
  3. Verify the key exists at C:\ProgramData\bbs-agent\ssh_key

Installer Fails with "Access Denied" on Borg Files

If re-running the installer fails because Borg files are locked:

  1. Ensure no borg processes are running: Get-Process -Name borg -ErrorAction SilentlyContinue | Stop-Process -Force
  2. Stop the service: Stop-Service BorgBackupAgent
  3. Wait a few seconds and re-run the installer

The installer includes retry logic for locked files, but in rare cases a manual process kill may be needed.

See also: Linux Agent Setup | macOS Agent Setup | Managing Clients | Backup Plans

📖 User Manual

Getting Started

Using BBS

Monitoring

Administration

Reference

Clone this wiki locally