Agent Installation & Usage

Install and manage the SimpleBackups Agent on your servers, containers, and clusters.

The SimpleBackups Agent is a lightweight process that runs on your infrastructure and executes backup jobs without requiring inbound SSH access. It connects outbound to SimpleBackups over HTTPS, receives backup instructions, and reports results. This guide covers installation on bare-metal servers, Docker containers, and Kubernetes clusters.

Prerequisites

Before installing the agent, make sure the following tools are available on the target machine:

curl — required for the installation script
gnu-tar — required on macOS only (brew install gnu-tar)

Depending on the type of backups you plan to run, you may also need database client tools:

MySQL / MariaDB: mysql, mysqldump
PostgreSQL: pg_dump, pg_dumpall
MongoDB: mongodump
File backups: no additional tools required

Getting your agent token

Each server you connect needs its own unique agent token. To get one:

Go to my.simplebackups.com/server/create
Select Agent as the connection method
Copy the token displayed on screen (for example, 5496Yl0m)

Standard installation

Run the installation script with your token:

bash

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

The script will:

Download the correct binary for your OS and architecture
Install the agent to /usr/local/bin/simplebackups-agent
Register your token
Configure a process manager (systemd or supervisor) to keep the agent running
Start the agent

If you need to reinstall or reconnect a server, uninstall the existing agent first:

bash

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

Docker installation

You can run the agent inside a Docker container. Three approaches are available depending on your setup.

Docker run

bash

SB_AGENT_TOKEN="YOUR_AGENT_TOKEN" docker run -d \
  --name simplebackups-agent \
  --network host \
  --restart unless-stopped \
  --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"

Docker Compose

Create a docker-compose.yml file:

yaml

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

Start the container:

bash

SB_AGENT_TOKEN="YOUR_AGENT_TOKEN" docker-compose up -d

Docker Swarm with secrets

For production environments, store your token as a Docker secret instead of an environment variable:

bash

echo "YOUR_AGENT_TOKEN" > agent_token.txt
docker secret create sb_agent_token agent_token.txt
rm 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"

Verifying the container

Regardless of the method you use, verify that the agent started correctly:

bash

docker logs -f simplebackups-agent

You should see output similar to:

plain

[SimpleBackups] Agent Version: 0.7.0
[SimpleBackups] Checking for pending task results...
[SimpleBackups] No pending task posts found.
[SimpleBackups] Connection established.

Kubernetes installation

To deploy the agent in a Kubernetes cluster, store the token as a secret and reference it in a Deployment.

Create the secret:

bash

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

Create a file called simplebackups-agent.yaml:

yaml

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 and verify:

bash

kubectl apply -f simplebackups-agent.yaml
kubectl get pods -l app=simplebackups-agent
kubectl logs -l app=simplebackups-agent -f

Process management

On standard Linux installations, the agent automatically detects and configures the best available process manager:

systemd — preferred on modern Linux distributions
supervisor — used as a fallback when systemd is not available
Manual mode — when neither is available, or when you pass the --manual-startup flag

The configured process manager ensures the agent restarts automatically after a crash or system reboot. Docker and Kubernetes installations always use manual mode, relying on the container runtime for restarts instead.

Managing the agent

Check status

bash

simplebackups-agent --status

Example output:

plain

[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, stop, and restart

bash

simplebackups-agent --start
simplebackups-agent --stop
simplebackups-agent --restart

Update

The agent updates itself automatically when a new version is available. You can also trigger an update manually:

bash

simplebackups-agent --self-update

Uninstall

bash

simplebackups-agent --uninstall

This stops the agent, removes the binary, deletes configuration and data files, and removes the process manager service entry.

Viewing logs

How you access logs depends on which process manager the agent is using.

systemd

bash

journalctl -u simplebackups-agent -n 100
journalctl -u simplebackups-agent -f

Supervisor

bash

supervisorctl tail simplebackups-agent
supervisorctl tail -f simplebackups-agent

Manual mode

Check the data directory shown by simplebackups-agent --status for log files.

Troubleshooting

Agent not starting

Check whether the agent is already running, then review the logs:

bash

simplebackups-agent --status

# systemd
journalctl -u simplebackups-agent -n 50

# supervisor
supervisorctl tail simplebackups-agent stderr

If the agent appears stuck, restart it:

bash

simplebackups-agent --restart

Authentication errors

If you see token-related errors:

Verify your token at my.simplebackups.com
Confirm that only one server is using the token
If needed, reinstall with a new token:

bash

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

Missing database tools

If backups fail with "command not found" errors, install the required client tools:

bash

# MySQL / MariaDB — Ubuntu/Debian
apt-get install mysql-client

# MySQL / MariaDB — CentOS/RHEL
yum install mysql

# PostgreSQL — Ubuntu/Debian
apt-get install postgresql-client

# PostgreSQL — CentOS/RHEL
yum install postgresql

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

# MongoDB — CentOS/RHEL
yum install mongodb-database-tools

Permission errors

If the installation script fails with permission errors, run it with sudo:

bash

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

Update fails

If --self-update does not work, check your internet connectivity and fall back to a fresh install:

bash

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

Security best practices

Store your agent token securely. Never commit it to version control.
Use Kubernetes Secrets or Docker Secrets in production environments.
Each token should only be active on one server at a time.
The agent connects outbound over HTTPS only — no inbound ports need to be opened.

How your data is processedUnderstand what data SimpleBackups accesses and how it is handled.Backup workersCompare the agent with other backup execution methods.

Agent Installation & Usage ​

Prerequisites ​

Getting your agent token ​

Standard installation ​

Docker installation ​

Docker run ​

Docker Compose ​

Docker Swarm with secrets ​

Verifying the container ​

Kubernetes installation ​

Process management ​

Managing the agent ​

Check status ​

Start, stop, and restart ​

Update ​

Uninstall ​

Viewing logs ​

systemd ​

Supervisor ​

Manual mode ​

Troubleshooting ​

Agent not starting ​

Authentication errors ​

Missing database tools ​

Permission errors ​

Update fails ​

Security best practices ​

Agent Installation & Usage

Prerequisites

Getting your agent token

Standard installation

Docker installation

Docker run

Docker Compose

Docker Swarm with secrets

Verifying the container

Kubernetes installation

Process management

Managing the agent

Check status

Start, stop, and restart

Update

Uninstall

Viewing logs

systemd

Supervisor

Manual mode

Troubleshooting

Agent not starting

Authentication errors

Missing database tools

Permission errors

Update fails

Security best practices