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:

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

Step 2: Download the Configuration File

After creating the device:

Open the device details page
Click "Download Configuration" to get pluton-agent.json
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 a protected environment file
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:

Open System Settings → Privacy & Security → Full Disk Access
Click the + button
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

Navigate to Devices in Pluton
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:

Component	Location	Description
Service user	`_pluton-agent`	Dedicated non-root user for running the agent
Agent binary	`/usr/local/pluton-agent/bin/pluton-agent`	Main agent executable (owned by root)
Restic	`/usr/local/pluton-agent/bin/restic`	Backup tool
Rclone	`/usr/local/pluton-agent/bin/rclone`	Cloud sync tool
Helper scripts	`/usr/local/pluton-agent/bin/*.sh`	File, metrics, and update helpers
Configuration	`/etc/pluton-agent/pluton-agent.env`	Environment configuration
Data directory	`/var/lib/pluton-agent/`	Agent data and state
Sudoers	`/etc/sudoers.d/pluton-agent`	Passwordless sudo for restic/rclone/helpers
LaunchDaemon	`/Library/LaunchDaemons/com.pluton.agent.plist`	Service 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

Using `selfupdate` (Recommended)

Agent v0.12.0 and later can update themselves in place, without Homebrew:

sudo pluton-agent selfupdate

Check first without installing anything:

pluton-agent version

The update process:

Downloads the latest release and verifies its checksum
Confirms the new binary runs and reports the expected version
Stops the service, replaces the binaries, and starts it again
Verifies the service stays up, and rolls back to the previous version if it does not

Configuration, credentials, and device identity are preserved.

Useful options:

Option	Description
`--check`	Report whether an update is available and exit
`--version X.Y.Z`	Install a specific version instead of the latest
`--force`	Update even when the version is the same or older
`--yes` or `-y`	Do not ask for confirmation
`--no-restart`	Do not restart the service after the update

With Pluton PRO 0.20.0 or later, you can also update this device from the dashboard instead of signing in to it. See Updating Agents from the Pluton Dashboard.

Using Homebrew

For agents older than v0.12.0, upgrade with Homebrew. 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:

Downloads the latest agent package
Stops the running service
Updates binaries while preserving existing configuration
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

Check service status:

sudo launchctl list | grep com.pluton.agent

Check network connectivity:

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

Review agent logs:
```
tail -100 /var/log/pluton-agent.log
```

Service Fails to Start

Check the plist is loaded:

sudo launchctl list | grep com.pluton.agent

Check configuration:

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

Check error logs:

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

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:

Go to System Settings → Privacy & Security → Full Disk Access
Verify /usr/local/pluton-agent/bin/pluton-agent is listed and enabled

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 from pluton-agent.json are copied into 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

Purpose	Location
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`

Prerequisites​

Step 1: Create a Device in Pluton UI​

Step 2: Download the Configuration File​

Step 3: Install the Agent via Homebrew​

Add the Pluton Tap​

Install the Agent​

Step 4: Grant Full Disk Access​

Step 5: Verify Installation​

Check in Pluton UI​

Check Service Status​

Check Agent Version​

Configuration File Format​

What Gets Installed​

Managing the Agent Service​

Viewing Logs​

Upgrading the Agent​

Using selfupdate (Recommended)​

Using Homebrew​

Uninstalling the Agent​

Standard Uninstall​

Full Uninstall (Remove All Data)​

Troubleshooting​

Agent Shows "Offline" in Pluton UI​

Service Fails to Start​

Homebrew Install Fails with License Error​

Homebrew Install Fails with Config Error​

Permission Issues During Backup​

Security Considerations​

File Locations Reference​