Agent Installation & Usage Guide – SimpleBackups Help Center

Overview

The SimpleBackups Agent enables automated backups from your servers. This guide covers installation, configuration, and management of the agent across different platforms.

Prerequisites

Required Software

curl - Required for installation

Backup-specific tools - Depends on your backup type:

MySQL/MariaDB backups: mysql, mysqldump

PostgreSQL backups: pg_dump, pg_dumpall

MongoDB backups: mongodump

Files backups: No additional tools needed

macOS Specific

gnu-tar - Required for macOS installations

brew install gnu-tar

Getting Your Agent Token

Go to https://my.simplebackups.com/server/create

Select Agent as the connection method

Copy your unique agent token (e.g., 5496Yl0m)

⚠️ Important: Each token is unique per server. If you use the same token on multiple servers, only the most recently registered server will run backups.

Installation Methods

Standard Installation

Run the installation command with your agent token:

bash -c "$(curl -sSL 'https://get.simplebackups.app/agent.sh')" -- 'YOUR_AGENT_TOKEN'

Replace YOUR_AGENT_TOKEN with your actual token from the SimpleBackups dashboard.

Example:

bash -c "$(curl -sSL 'https://get.simplebackups.app/agent.sh')" -- '5496Yl0m'

The installer will:

✅ Download the appropriate binary for your OS and architecture

✅ Install the agent to /usr/local/bin/simplebackups-agent

✅ Initialize the agent with your token

✅ Automatically detect and configure the best process manager (systemd or supervisor)

✅ Start the agent

Re-installation or reconnection

simplebackups-agent --uninstall && bash -c "$(curl -sSL 'https://get.simplebackups.app/agent.sh')" -- 'YOUR_AGENT_TOKEN'

Stateless Installation

For repeated installations on ephemeral infrastructure, you can run the same command on multiple machines. However, remember that only one machine per token will actively run backups.

Docker

Option 1: Docker Run (Inline)

SB_AGENT_TOKEN="YOUR_AGENT_TOKEN" docker run -d \
  --name simplebackups-agent \
  --network host \
  --env SB_AGENT_TOKEN \
  ubuntu:22.04 \
  bash -c "set -e; \
           apt-get update; \
           apt-get install -y curl; \
           curl -sSL https://get.simplebackups.app/agent.sh | bash -s -- \$SB_AGENT_TOKEN; \
           SB_AGENT_TOKEN=\$SB_AGENT_TOKEN /usr/local/bin/simplebackups-agent --manual-startup"

Verify and check agent logs:

docker logs -f simplebackups-agent

You should see something like:

simplebackups-agent  | [SimpleBackups] Agent Version: 
simplebackups-agent  | [SimpleBackups] Checking for pending task results...
simplebackups-agent  | [SimpleBackups] No pending task posts found.
simplebackups-agent  | [SimpleBackups] Connection established.

Check running containers:

docker ps

You should see simplebackups-agent with status Up.

Option 2: Docker Compose

Create a docker-compose.yml:

services:
  simplebackups-agent:
    image: ubuntu:22.04
    container_name: simplebackups-agent
    network_mode: "host"
    environment:
      - SB_AGENT_TOKEN=${SB_AGENT_TOKEN}
    command: >
      bash -c "
        set -e;
        apt-get update;
        apt-get install -y curl;
        curl -sSL https://get.simplebackups.app/agent.sh | bash -s -- $SB_AGENT_TOKEN;
        SB_AGENT_TOKEN=$SB_AGENT_TOKEN /usr/local/bin/simplebackups-agent --manual-startup
      "
    restart: unless-stopped

Run with:

SB_AGENT_TOKEN="YOUR_AGENT_TOKEN" docker-compose up -d

Verify and check agent logs:

docker logs -f simplebackups-agent

You should see something like:

simplebackups-agent  | [SimpleBackups] Agent Version: 
simplebackups-agent  | [SimpleBackups] Checking for pending task results...
simplebackups-agent  | [SimpleBackups] No pending task posts found.
simplebackups-agent  | [SimpleBackups] Connection established.

Check running containers:

docker ps

You should see simplebackups-agent with status Up.

Option 3: Secure with Docker Secrets (Docker Swarm)

Create a secret file:

echo "YOUR_AGENT_TOKEN" > agent_token.txt

Use Docker secrets:

docker secret create sb_agent_token agent_token.txt

docker service create \
  --name simplebackups-agent \
  --secret sb_agent_token \
  --env SB_AGENT_TOKEN_FILE=/run/secrets/sb_agent_token \
  --restart-condition any \
  --network host \
  ubuntu:22.04 \
  bash -c "set -e; \
           apt-get update; \
           apt-get install -y curl; \
           export SB_AGENT_TOKEN=\$(cat /run/secrets/sb_agent_token); \
           curl -sSL https://get.simplebackups.app/agent.sh | bash -s -- \$SB_AGENT_TOKEN; \
           SB_AGENT_TOKEN=\$SB_AGENT_TOKEN /usr/local/bin/simplebackups-agent --manual-startup"

Check service status:

docker service ls

Check logs:

docker service logs -f simplebackups-agent

Kubernetes

Using Kubernetes Secrets (Recommended)

Create a Secret with your Agent Token:

kubectl create secret generic simplebackups-secret --from-literal=agent-token=YOUR_AGENT_TOKEN

Create a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: simplebackups-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: simplebackups-agent
  template:
    metadata:
      labels:
        app: simplebackups-agent
    spec:
      containers:
        - name: agent
          image: ubuntu:22.04
          command: ["/bin/bash", "-c"]
          args:
            - >
              apt-get update &&
              apt-get install -y curl &&
              bash -c "$(curl -sSL https://get.simplebackups.app/agent.sh)" -- "$SB_AGENT_TOKEN"
          env:
            - name: SB_AGENT_TOKEN
              valueFrom:
                secretKeyRef:
                  name: simplebackups-secret
                  key: agent-token
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "256Mi"
              cpu: "200m"
      restartPolicy: Always

Deploy:

kubectl apply -f simplebackups-agent.yaml

Verify:

kubectl get pods -l app=simplebackups-agent
kubectl logs -l app=simplebackups-agent -f

Process Management

The SimpleBackups Agent automatically detects and uses the best process manager available on your system:

Automatic Detection Priority (Linux)

systemd (preferred) - Modern Linux distributions

supervisor - Fallback for systems without systemd

Manual mode - If neither is available

What This Means for You

✅ You don't need to configure anything - the agent handles it automatically

✅ Auto-restart on crashes - The process manager ensures the agent stays running

✅ Starts on system boot - The agent will automatically start when your server reboots

Manual Mode

If you prefer to manage the agent process yourself (not recommended for production), use the --manual-startup flag:

simplebackups-agent --manual-startup

⚠️ Warning: In manual mode, you are responsible for:

Managing the Agent

Check Agent Status

simplebackups-agent --status

Example output:

[SimpleBackups] Agent Version: 0.7.0 (env: production)
[SimpleBackups] Data directory: /var/lib/simplebackups-agent
[SimpleBackups] Config directory: /etc/simplebackups-agent
✅ Agent is running (PID: 1234)

Start the Agent

simplebackups-agent --start

Stop the Agent

simplebackups-agent --stop

Restart the Agent

simplebackups-agent --restart

Update the Agent

The agent automatically updates itself when new versions are available. However, you can manually trigger an update:

simplebackups-agent --self-update

View Agent Version

simplebackups-agent --version

Uninstall the Agent

simplebackups-agent --uninstall

This will:

Stop the running agent

Remove the agent binary

Delete configuration and data files

Remove systemd/supervisor service configurations

Troubleshooting

Check if Agent is Running

simplebackups-agent --status

View Logs

For systemd:

# View recent logs
journalctl -u simplebackups-agent -n 100

# Follow logs in real-time
journalctl -u simplebackups-agent -f

For supervisor:

# View logs
supervisorctl tail simplebackups-agent

# Follow logs in real-time
supervisorctl tail -f simplebackups-agent

# Check supervisor status
supervisorctl status simplebackups-agent

For manual mode: Check the data directory shown by --status command for log files.

Common Issues

Agent Not Starting

Check if the agent is already running:

simplebackups-agent --status

Check system logs:

# systemd
journalctl -u simplebackups-agent -n 50

# supervisor
supervisorctl tail simplebackups-agent stderr

Try restarting:

simplebackups-agent --restart

Token Issues

If you see authentication errors:

Verify your token at https://my.simplebackups.com

Ensure only ONE server is using the token

Reinstall with the correct token:

simplebackups-agent --uninstall
bash -c "$(curl -sSL 'https://get.simplebackups.app/agent.sh')" -- 'YOUR_NEW_TOKEN'

Backup-Specific Tools Missing

If backups fail with "command not found" errors:

For MySQL/MariaDB:

# Ubuntu/Debian
apt-get install mysql-client

# CentOS/RHEL
yum install mysql

For PostgreSQL:

# Ubuntu/Debian
apt-get install postgresql-client

# CentOS/RHEL
yum install postgresql

For MongoDB:

# Ubuntu/Debian
apt-get install mongodb-database-tools

# CentOS/RHEL
yum install mongodb-database-tools

For macOS:

# Install gnu-tar
brew install gnu-tar

Agent Won't Update

If --self-update fails:

Check internet connectivity

Manually reinstall:

bash -c "$(curl -sSL 'https://get.simplebackups.app/agent.sh')" -- 'YOUR_AGENT_TOKEN'

Permission Issues

If you encounter permission errors:

# Run installation with sudo
sudo bash -c "$(curl -sSL 'https://get.simplebackups.app/agent.sh')" -- 'YOUR_AGENT_TOKEN'

Data and Config Locations

Find where the agent stores data:

simplebackups-agent --status

This shows:

Data directory: Where the agent stores operational data

Config directory: Where configuration is stored

Support

If you need help:

Check the troubleshooting section

View logs using the commands above

Include:

Output of simplebackups-agent --status

Relevant log entries

Your operating system and version

Security Notes

🔒 Always store your agent token securely

🔒 Use Kubernetes Secrets or Docker Secrets in production

🔒 Never commit tokens to version control

🔒 Each token should only be used on ONE active server

Need to create a new agent? Visit https://my.simplebackups.com/server/create