macOS Agent Setup

macOS Agent Setup

This guide covers installing and configuring the BBS backup agent on macOS. The agent runs as a system daemon via launchd and supports both Apple Silicon (M1/M2/M3/M4) and Intel Macs.

Prerequisites

Before installing the agent on your Mac, ensure you have:

• macOS 12 (Monterey) or later (earlier versions may work but are untested)
• Homebrew installed — the installer uses Homebrew to install BorgBackup and Python 3. Install from https://brew.sh
• Administrator access — the installer requires sudo to install system-wide services
• Network access to your BBS server (HTTPS, typically port 443)

Install Homebrew (if not already installed)

Open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install the required packages:

brew install borgbackup python3

Note: The agent installer will attempt to install these automatically via Homebrew, but it's recommended to install them beforehand to avoid issues.

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 Mac (e.g., "Marcs-MacBook-Pro")
4. Click Create Client
5. Copy the install command displayed after creation — you'll need this in the next step

Step 2: Install the Agent

Open Terminal on your Mac and paste the install command from Step 1. It will look like this:

curl -s https://your-bbs-server.com/get-agent | sudo bash -s -- \
    --server https://your-bbs-server.com \
    --key YOUR_API_KEY

Replace your-bbs-server.com with your BBS server URL and YOUR_API_KEY with the key from the BBS web interface. You will be prompted for your Mac login password (for sudo).

The installer will:

1. Detect macOS and install BorgBackup via Homebrew (if not already installed)
2. Download the agent script to /opt/bbs-agent/
3. Download the compiled macOS wrapper binary and create a .app bundle for Full Disk Access
4. Generate a launchd service configuration
5. Register the agent with your BBS server
6. Start the agent service

You should see output similar to:

╔══════════════════════════════════════════════════════════════╗
║         Borg Backup Server — Agent Installer              ║
╚══════════════════════════════════════════════════════════════╝

  → Detecting operating system...
  ✓ Detected: macOS 15.3
  → Checking for Borg Backup...
  ✓ Already installed: borg 1.4.0
  → Installing agent files...
  ✓ Agent downloaded to /opt/bbs-agent
  ✓ Configuration saved to /etc/bbs-agent/config.ini
  → Setting up SSH keys...
  ✓ SSH key installed to /etc/bbs-agent/ssh_key
  → Installing system service...
  ✓ Service installed (launchd)

╔══════════════════════════════════════════════════════════════╗
║                  Installation Complete!                     ║
╚══════════════════════════════════════════════════════════════╝

Step 3: Grant Full Disk Access

This is the most important step for macOS. Without Full Disk Access (FDA), the agent cannot back up files in protected locations such as Desktop, Documents, Downloads, and external volumes.

Why is this needed? macOS requires explicit user consent before any program can access protected directories. This is an Apple security requirement and cannot be bypassed programmatically.

Grant FDA to the BBS Agent

1. Open System Settings (or System Preferences on older macOS)

2. Navigate to Privacy & Security > Full Disk Access

3. Click the + button (you may need to click the lock icon and enter your password first)

4. A file browser dialog will appear. The BBS Agent app is installed in a system directory that isn't visible by default. Press Cmd+Shift+G to open the "Go to folder" dialog

5. Type the following path and press Enter:

   /opt/bbs-agent/BBS Agent.app
   

6. Select BBS Agent.app and click Open (or Add)

7. Verify that BBS Agent now appears in the Full Disk Access list with its toggle enabled

8. Restart the agent to apply the new permissions:

   sudo launchctl kickstart -k system/com.borgbackupserver.agent

Verify Full Disk Access is Working

After granting FDA and restarting the agent, run a test backup from the BBS web interface. Check the agent log for any permission errors:

tail -f /var/log/bbs-agent.log

If backups complete without Operation not permitted errors, FDA is working correctly.

Step 4: 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).

If the agent doesn't come online, see the Troubleshooting section below.

How It Works

Architecture

On macOS, the BBS agent runs differently than on Linux:

• Wrapper binary — A compiled universal binary (bbs-mac-agent) finds the correct Python 3 installation and launches the agent script. This binary is packaged as a .app bundle (BBS Agent.app) so that macOS recognizes it in Full Disk Access settings
• FDA inheritance — When you grant Full Disk Access to BBS Agent.app, all child processes (Python, BorgBackup) inherit the permission automatically
• launchd — macOS uses launchd (not systemd) to manage system services. The agent runs as a LaunchDaemon, starting automatically on boot and restarting if it crashes

File Locations

Path	Description
/opt/bbs-agent/bbs-agent.py	Agent script
/opt/bbs-agent/BBS Agent.app	Wrapper app bundle (for FDA)
/opt/bbs-agent/bbs-mac-agent	Compiled wrapper binary
/opt/bbs-agent/uninstall.sh	Uninstaller script
/etc/bbs-agent/config.ini	Agent configuration
/etc/bbs-agent/ssh_key	SSH private key for borg access
/Library/LaunchDaemons/com.borgbackupserver.agent.plist	launchd service definition
/var/log/bbs-agent.log	Agent log file

Service Management

Common Commands

# Check if the agent is running
sudo launchctl list | grep borgbackupserver

# View live agent logs
tail -f /var/log/bbs-agent.log

# View last 50 log lines
tail -50 /var/log/bbs-agent.log

# Restart the agent
sudo launchctl kickstart -k system/com.borgbackupserver.agent

# Stop the agent
sudo launchctl bootout system/com.borgbackupserver.agent

# Start the agent (after stopping)
sudo launchctl bootstrap system /Library/LaunchDaemons/com.borgbackupserver.agent.plist

Configuration

The agent configuration is stored at /etc/bbs-agent/config.ini:

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

[agent]
poll_interval = 30

After editing the configuration, restart the agent:

sudo launchctl kickstart -k system/com.borgbackupserver.agent

Uninstalling

To completely remove the agent from your Mac:

sudo /opt/bbs-agent/uninstall.sh

This removes:

• The launchd service
• Agent files in /opt/bbs-agent/
• Configuration and SSH key in /etc/bbs-agent/
• The log file at /var/log/bbs-agent.log

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

You should also remove BBS Agent from Full Disk Access in System Settings after uninstalling.

Troubleshooting

Agent Not Coming Online

Check if the service is running:

sudo launchctl list | grep borgbackupserver

If no output is shown, the service isn't loaded. Bootstrap it:

sudo launchctl bootstrap system /Library/LaunchDaemons/com.borgbackupserver.agent.plist

Check the agent log:

tail -50 /var/log/bbs-agent.log

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

Verify network connectivity:

curl -I https://your-bbs-server.com

Backups Failing with "Operation not permitted"

This means Full Disk Access has not been granted or is not active:

1. Open System Settings > Privacy & Security > Full Disk Access
2. Verify BBS Agent is listed and its toggle is on
3. If it's not listed, follow Step 3 above
4. After granting FDA, restart the agent:

   sudo launchctl kickstart -k system/com.borgbackupserver.agent

BBS Agent.app Not Appearing in File Dialog

When adding the app to Full Disk Access, if you can't find it:

1. In the file browser dialog, press Cmd+Shift+G
2. Type /opt/bbs-agent/BBS Agent.app and press Enter
3. The app should now be selectable

If the app doesn't exist, re-run the installer to create it.

Homebrew Not Found

The installer requires Homebrew for installing BorgBackup and Python 3. Install Homebrew first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then re-run the agent installer.

Python 3 Not Found

If the installer can't find Python 3, install it via Homebrew:

brew install python3

The agent supports Python 3 at these locations:

• /opt/homebrew/bin/python3 (Apple Silicon — Homebrew default)
• /usr/local/bin/python3 (Intel — Homebrew default)
• /usr/bin/python3 (macOS built-in, if available)

Agent Log Shows Duplicate Lines

If you're seeing every log line printed twice, this was fixed in agent version 2.8.0. Update the agent from the BBS web interface: go to the client detail page and click Update Agent.

---

See also: Agent Setup (Linux) | Managing Clients | Backup Plans