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:

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., "Ubuntu Desktop - 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: 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
Configuration	/etc/pluton-agent/pluton-agent.env	Environment configuration
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

To update an existing installation, 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:

1. Stops the running service
2. Replaces binaries with new versions
3. Restarts the service
4. 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

1. Check service status:

   sudo systemctl status pluton-agent

2. Check network connectivity:

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

3. Review agent logs:

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

Service Fails to Start

1. Check configuration:

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

2. Verify file permissions:

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

3. Test binary manually:

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

AppImage Won't Run

1. Check if FUSE is installed:

   # For Ubuntu/Debian
   sudo apt install fuse libfuse2
   
   # For Fedora
   sudo dnf install fuse fuse-libs

2. 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 securely in the OS keyring when available, or in a protected environment file with 640 permissions
• 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
Environment config	/etc/pluton-agent/pluton-agent.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

---