Skip to main content

Installing Agent on macOS

This guide walks you through installing the Pluton Agent on macOS using Homebrew. The agent enables centralized backup management for your Mac desktops, laptops, and workstations.

Prerequisites​

Before installing the Pluton Agent:

  • macOS Monterey (12) or later
  • Administrator privileges on the target machine
  • Active Pluton PRO license with available device slots
  • Homebrew installed (brew.sh)
  • Supported architectures: Intel (x86_64), Apple Silicon (arm64)

Step 1: Create a Device in Pluton UI​

Before installing the agent, create a device entry in Pluton:

  1. Navigate to Devices in the main navigation
  2. Click "Add Device" in the top-right corner
  3. Fill in the device details:
    • Device Name: A descriptive name (e.g., "MacBook Pro - Development")
    • Device Type: Select appropriate type (Device, Virtual Machine, etc.)
  4. Click "Create Device"
  5. Download the configuration file (pluton-agent.json)

Step 2: Download the Configuration File​

After creating the device:

  1. Open the device details page
  2. Click "Download Configuration" to get pluton-agent.json
  3. Save this file — you'll need it during installation

Step 3: Install the Agent via Homebrew​

Add the Pluton Tap​

If you haven't already added the Pluton Homebrew tap:

brew tap plutonhq/pluton

Install the Agent​

Set the required environment variables and install:

export HOMEBREW_PLUTON_AGENT_LICENSE="YOUR_LICENSE_KEY"
export HOMEBREW_PLUTON_AGENT_CONFIG="/path/to/pluton-agent.json"
brew install plutonhq/pluton/pluton-agent

The Homebrew cask will:

  • Download the agent package (verified with your license key)
  • Create a dedicated _pluton-agent service user (non-root)
  • Install binaries to /usr/local/pluton-agent/bin/
  • Parse your configuration file and write credentials
  • Configure sudoers for privileged backup operations
  • Create the launchd service (runs as _pluton-agent)
  • Start the agent automatically

Step 4: Grant Full Disk Access​

To back up files in protected directories (Desktop, Documents, Downloads, etc.), you must grant Full Disk Access to the agent binary:

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Click the + button
  3. Navigate to and add: /usr/local/pluton-agent/bin/pluton-agent
tip

You can press Cmd+Shift+G in the file picker dialog to type the path directly.

Step 5: Verify Installation​

Check in Pluton UI​

  1. Navigate to Devices in Pluton
  2. Find your device — it should show as "Online"

Check Service Status​

# Check if the launchd service is running
sudo launchctl list | grep com.pluton.agent

Check Agent Version​

/usr/local/pluton-agent/bin/pluton-agent --version

Configuration File Format​

The pluton-agent.json file should contain:

{
  "agentId": "your-agent-id",
  "apiKey": "your-api-key",
  "signingKey": "your-signing-key",
  "serverUrl": "https://your-pluton-server-ip-or-domain.com",
  "encryptionKey": "your-32-character-encryption-key",
  "licenseKey": "your-license-key"
}

What Gets Installed​

The Homebrew cask installs the following:

ComponentLocationDescription
Service user_pluton-agentDedicated non-root user for running the agent
Agent binary/usr/local/pluton-agent/bin/pluton-agentMain agent executable (owned by root)
Restic/usr/local/pluton-agent/bin/resticBackup tool
Rclone/usr/local/pluton-agent/bin/rcloneCloud sync tool
Helper scripts/usr/local/pluton-agent/bin/*.shFile, metrics, and update helpers
Configuration/etc/pluton-agent/pluton-agent.envEnvironment configuration
Data directory/var/lib/pluton-agent/Agent data and state
Sudoers/etc/sudoers.d/pluton-agentPasswordless sudo for restic/rclone/helpers
LaunchDaemon/Library/LaunchDaemons/com.pluton.agent.plistService definition (runs as _pluton-agent)

Managing the Agent Service​

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

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

# Start the agent
sudo launchctl bootstrap system /Library/LaunchDaemons/com.pluton.agent.plist

Viewing Logs​

# View agent output log
tail -f /var/log/pluton-agent.log

# View agent error log
tail -f /var/log/pluton-agent.error.log

Upgrading the Agent​

On upgrade, only the license key is needed — existing agent credentials are preserved automatically:

export HOMEBREW_PLUTON_AGENT_LICENSE="YOUR_LICENSE_KEY"
brew update
brew upgrade pluton-agent

The upgrade process:

  1. Downloads the latest agent package
  2. Stops the running service
  3. Updates binaries while preserving existing configuration
  4. Restarts the service

Uninstalling the Agent​

Standard Uninstall​

Stops the service and removes the LaunchDaemon plist, but preserves configuration and data for potential reinstall:

brew uninstall pluton-agent

Full Uninstall (Remove All Data)​

Removes everything including binaries, configuration, data, and logs:

brew uninstall --zap pluton-agent

This will:

  • Stop and remove the launchd service
  • Remove agent binaries (/usr/local/pluton-agent/)
  • Remove configuration (/etc/pluton-agent/)
  • Remove sudoers file (/etc/sudoers.d/pluton-agent)
  • Remove the _pluton-agent service user
  • Remove data directory (/var/lib/pluton-agent/)
  • Remove log files

Troubleshooting​

Agent Shows "Offline" in Pluton UI​

  1. Check service status:

    sudo launchctl list | grep com.pluton.agent

  2. Check network connectivity:

    # Test connection to the server
    curl -I https://your-pluton-server-ip-or-domain.com

  3. Review agent logs:

    tail -100 /var/log/pluton-agent.log

Service Fails to Start​

  1. Check the plist is loaded:

    sudo launchctl list | grep com.pluton.agent

  2. Check configuration:

    sudo cat /etc/pluton-agent/pluton-agent.env

  3. Check error logs:

    tail -100 /var/log/pluton-agent.error.log

  4. Re-bootstrap the service:

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

Homebrew Install Fails with License Error​

Ensure you've set the license key environment variable before running brew install:

export HOMEBREW_PLUTON_AGENT_LICENSE="YOUR_LICENSE_KEY"

Homebrew Install Fails with Config Error​

On first install, the configuration file is required:

export HOMEBREW_PLUTON_AGENT_CONFIG="/path/to/pluton-agent.json"

Make sure the file exists and contains all required fields.

Permission Issues During Backup​

Ensure Full Disk Access has been granted:

  1. Go to System Settings → Privacy & Security → Full Disk Access
  2. Verify /usr/local/pluton-agent/bin/pluton-agent is listed and enabled
  3. Restart the agent after granting access: 
    sudo launchctl kickstart -k system/com.pluton.agent

Security Considerations​

  • The agent runs as a dedicated non-root user (_pluton-agent), not as root
  • Binaries in /usr/local/pluton-agent/ are owned by root:wheel and not writable by the agent user
  • Credentials are stored in a protected environment file (/etc/pluton-agent/pluton-agent.env) with 640 permissions, owned by _pluton-agent:staff
  • Privileged operations (restic, rclone, helper scripts) are executed via sudoers (/etc/sudoers.d/pluton-agent), granting only the specific commands needed
  • The LaunchDaemon plist is owned by root:wheel with 644 permissions
  • All communication with the Pluton server is over HTTPS, authenticated using API keys
  • The data directory (/var/lib/pluton-agent/) has 700 permissions, owned by _pluton-agent

Important: After installation, delete the pluton-agent.json configuration file as it contains sensitive credentials:

rm -f /path/to/pluton-agent.json

File Locations Reference​

PurposeLocation
Service user_pluton-agent (UID 400–499)
Agent binary/usr/local/pluton-agent/bin/pluton-agent
Restic binary/usr/local/pluton-agent/bin/restic
Rclone binary/usr/local/pluton-agent/bin/rclone
Helper scripts/usr/local/pluton-agent/bin/*.sh
Sudoers file/etc/sudoers.d/pluton-agent
Environment config/etc/pluton-agent/pluton-agent.env
Data directory/var/lib/pluton-agent/
LaunchDaemon plist/Library/LaunchDaemons/com.pluton.agent.plist
Output log/var/log/pluton-agent.log
Error log/var/log/pluton-agent.error.log