Installing Agent on Linux Desktop

This guide walks you through installing the Pluton Agent on Linux desktop systems using the AppImage format. The AppImage provides a self-contained package that works across all major Linux distributions without requiring root access for the download.

Prerequisites

Before installing the Pluton Agent:

Linux desktop system with systemd (Ubuntu, Fedora, Debian, Arch, etc.)
Root/sudo access for installation
Active Pluton PRO license with available device slots
Supported architectures: x86_64 (amd64), ARM64 (aarch64)

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., "Ubuntu Desktop - 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: Download the AppImage

Download the Pluton Agent AppImage for your architecture either from the Pluton Device UI interface or from your Pluton PRO's User account dashboard.

Step 4: Install the Agent

Option A: Install with JSON Configuration File (Recommended)

Run the AppImage with the install command and your configuration file:

sudo ./pluton-agent-linux-amd64.AppImage install --secret-file /path/to/pluton-agent.json

The installer will:

Extract binaries to /opt/pluton-agent/
Create the pluton-agent system user
Configure the systemd service
Set up proper permissions and sudoers rules
Start the agent service

Option B: Interactive Installation

Run the installer without a config file to enter credentials interactively:

sudo ./pluton-agent-linux-amd64.AppImage install

You will be prompted to enter:

Agent ID
Server URL
API Key
Signing Key
Encryption Key
License Key

Option C: Piped Input (Automation)

For CI/CD or automated deployments, pipe the configuration via stdin:

cat << EOF | sudo ./pluton-agent-linux-amd64.AppImage install
AGENT_ID=your-agent-id
SERVER_URL=https://your-pluton-server-ip-or-domain.com
API_KEY=your-api-key
SIGNING_KEY=your-signing-key
ENCRYPTION_KEY=your-encryption-key
LICENSE_KEY=your-license-key
EOF

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 AppImage installer creates the following:

Component	Location	Description
Agent binary	`/opt/pluton-agent/bin/pluton-agent`	Main agent executable
Restic	`/opt/pluton-agent/bin/restic`	Backup tool
Rclone	`/opt/pluton-agent/bin/rclone`	Cloud sync tool
Config file	`/etc/pluton-agent/pluton-agent.env`	Agent ID, API key, server URL, and license key
Secret file	`/etc/pluton-agent/pluton-agent.enc.env`	Encryption key and signing key
Data directory	`/var/lib/pluton-agent/`	Agent data and state
Systemd service	`/etc/systemd/system/pluton-agent.service`	Service definition
Sudoers config	`/etc/sudoers.d/pluton-agent`	Privilege escalation rules
Wrapper scripts	`/usr/local/bin/prclone`, `/usr/local/bin/prestic`	CLI wrappers
Agent symlink	`/usr/local/bin/pluton-agent`	System-wide agent command

Verify Installation

Check if the agent is running:

# Check service status
sudo systemctl status pluton-agent

# View recent logs
sudo journalctl -u pluton-agent -n 50

# Check agent version
pluton-agent --version

# Check in Pluton UI - device should show as "Online"

Managing the Agent Service

# Start the agent
sudo systemctl start pluton-agent

# Stop the agent
sudo systemctl stop pluton-agent

# Restart the agent
sudo systemctl restart pluton-agent

# View live logs
sudo journalctl -u pluton-agent -f

# Check status
sudo systemctl status pluton-agent

Using the CLI Wrappers

The installation creates wrapper scripts for direct command-line access:

# Use restic with agent configuration
prestic snapshots

# Use rclone with agent configuration
prclone listremotes

# Run agent commands directly
pluton-agent --version

Updating the Agent

Using `selfupdate` (Recommended)

Agent v0.12.0 and later can update themselves in place, without downloading an AppImage:

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 the AppImage

For agents older than v0.12.0, use the --update flag:

# Download the latest AppImage
wget https://dl.usepluton.com/agent/releases/latest/pluton-agent-linux-amd64.AppImage
chmod +x pluton-agent-linux-amd64.AppImage

# Run update (preserves configuration)
sudo ./pluton-agent-linux-amd64.AppImage install --update

The update process:

Stops the running service
Replaces binaries with new versions
Restarts the service
Preserves all configuration and data

Uninstalling the Agent

To completely remove the Pluton Agent:

# Using the AppImage
sudo ./pluton-agent-linux-amd64.AppImage uninstall

# Or download and run the uninstall script
curl -sSL https://dl.usepluton.com/agent/scripts/uninstall-appimage.sh | sudo bash

Uninstall Options

Option	Description
`--force` or `-f`	Skip confirmation prompt
`--keep-data`	Keep data directory (useful for reinstall)
`--help` or `-h`	Show help message

Example keeping data:

sudo ./pluton-agent-linux-amd64.AppImage uninstall --keep-data

This will:

Stop and disable the systemd service
Remove agent binaries and installation directory
Remove configuration directory
Remove sudoers configuration
Remove the dedicated pluton-agent user
Remove data directory (unless --keep-data is used)

Troubleshooting

Agent Shows "Offline" in Pluton UI

Check service status:
```
sudo systemctl status pluton-agent
```

Check network connectivity:

# Test connection to the server
nc -zv your-pluton-server-ip

Review agent logs:

sudo journalctl -u pluton-agent -n 100 --no-pager

Service Fails to Start

Check configuration:

sudo ls -l /etc/pluton-agent/pluton-agent.env /etc/pluton-agent/pluton-agent.enc.env

Verify file permissions:

ls -la /etc/pluton-agent/
ls -la /var/lib/pluton-agent/

Test binary manually:

sudo -u pluton-agent /opt/pluton-agent/bin/pluton-agent --version

AppImage Won't Run

Check if FUSE is installed:

# For Ubuntu/Debian
sudo apt install fuse libfuse2

# For Fedora
sudo dnf install fuse fuse-libs

Extract and run directly:

./pluton-agent-linux-amd64.AppImage --appimage-extract
sudo ./squashfs-root/AppRun install --secret-file /path/to/config.json

Permission Denied Errors

Ensure the sudoers file is correctly configured:

sudo visudo -c -f /etc/sudoers.d/pluton-agent

Security Considerations

The agent runs as a dedicated pluton-agent user with limited privileges
Secrets are stored in /etc/pluton-agent/pluton-agent.env and /etc/pluton-agent/pluton-agent.enc.env
Both environment files are protected with 600 permissions, and /etc/pluton-agent/ is locked down for the service user
The sudoers configuration grants only specific, necessary privileges for backup operations
All communication with the Pluton server is over HTTPS, authenticated using API keys

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
Agent binary	`/opt/pluton-agent/bin/pluton-agent`
Restic binary	`/opt/pluton-agent/bin/restic`
Rclone binary	`/opt/pluton-agent/bin/rclone`
Config file	`/etc/pluton-agent/pluton-agent.env`
Secret file	`/etc/pluton-agent/pluton-agent.enc.env`
Rclone config	`/etc/pluton-agent/rclone.conf`
Data directory	`/var/lib/pluton-agent/`
Progress files	`/var/lib/pluton-agent/progress/`
Identity keys	`/var/lib/pluton-agent/identity/`
Service file	`/etc/systemd/system/pluton-agent.service`
Sudoers file	`/etc/sudoers.d/pluton-agent`

Prerequisites​

Step 1: Create a Device in Pluton UI​

Step 2: Download the Configuration File​

Step 3: Download the AppImage​

Step 4: Install the Agent​

Option A: Install with JSON Configuration File (Recommended)​

Option B: Interactive Installation​

Option C: Piped Input (Automation)​

Configuration File Format​

What Gets Installed​

Verify Installation​

Managing the Agent Service​

Using the CLI Wrappers​

Updating the Agent​

Using selfupdate (Recommended)​

Using the AppImage​

Uninstalling the Agent​

Uninstall Options​

Troubleshooting​

Agent Shows "Offline" in Pluton UI​

Service Fails to Start​

AppImage Won't Run​

Permission Denied Errors​

Security Considerations​

File Locations Reference​