@backuphero.io/agent

The official BackupHero agent for automated server backups powered by restic.

Features

• Lightweight backup agent running on your servers
• Powered by restic for efficient, encrypted backups
• Supports file system, MySQL, PostgreSQL, and MongoDB backups
• Automatic scheduling via cron expressions
• Real-time status updates via WebSocket
• S3-compatible storage support (AWS S3, Wasabi, Backblaze B2, MinIO, etc.)

Requirements

• Node.js 20.x or higher
• restic (installed automatically by the install script)
• Linux, macOS, or Windows

Installation

Quick Install (Recommended)

Run the install script as root:

curl -sSL https://get.backuphero.io | sudo bash

With options:

curl -sSL https://get.backuphero.io | sudo bash -s -- --key YOUR_API_KEY

Manual Install via npm

npm install -g @backuphero.io/agent

Install Specific Version

npm install -g @backuphero.io/[email protected]

Or via the install script:

curl -sSL https://get.backuphero.io | sudo bash -s -- --version 0.1.0

Configuration

After installation, configure the agent with your API key from the BackupHero dashboard:

backuphero-agent configure --key YOUR_API_KEY

With custom server URL (for self-hosted):

backuphero-agent configure \
  --key YOUR_API_KEY \
  --server wss://ws.your-domain.com \
  --config /etc/backuphero/backuphero.json

Usage

Start the Agent

backuphero-agent start --config /etc/backuphero/backuphero.json

Check Status

backuphero-agent status --config /etc/backuphero/backuphero.json

Manual Backup

Trigger a backup manually:

backuphero-agent backup --job JOB_ID --config /etc/backuphero/backuphero.json

Running as a Service

systemd (Linux)

The install script creates a systemd service automatically. Manage it with:

# Start the service
sudo systemctl start backuphero-agent

# Enable auto-start on boot
sudo systemctl enable backuphero-agent

# Check status
sudo systemctl status backuphero-agent

# View logs
sudo journalctl -u backuphero-agent -f

launchd (macOS)

# Load and start
sudo launchctl load /Library/LaunchDaemons/io.backuphero.agent.plist

# Stop and unload
sudo launchctl unload /Library/LaunchDaemons/io.backuphero.agent.plist

Configuration File

The agent stores its configuration in a JSON file (default: ./backuphero.json):

{
  "agentKey": "bhkey_...",
  "serverUrl": "wss://ws.backuphero.io",
  "resticPath": "restic",
  "logLevel": "info"
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | BACKUPHERO_AGENT_KEY | Agent API key | - | | BACKUPHERO_SERVER_URL | WebSocket server URL | wss://ws.backuphero.io | | BACKUPHERO_CONFIG | Path to config file | ./backuphero.json | | LOG_LEVEL | Logging level (debug, info, warn, error) | info |

Backup Types

File System Backup

Backs up directories and files using restic's efficient deduplication.

MySQL Backup

Uses mysqldump to create consistent database backups.

PostgreSQL Backup

Uses pg_dump for PostgreSQL database backups.

MongoDB Backup

Uses mongodump for MongoDB database backups.

Security

• Agent keys are hashed before storage (SHA-256)
• All backup data is encrypted by restic with AES-256
• Communication with the server uses WebSocket over TLS
• Credentials are stored encrypted in the configuration

Troubleshooting

Agent won't connect

1. Verify your API key is correct
2. Check network connectivity to the WebSocket server
3. Ensure firewall allows outbound WebSocket connections

Backups failing

1. Check restic is installed: restic version
2. Verify storage credentials in the dashboard
3. Check disk space on the backup target
4. Review logs: journalctl -u backuphero-agent -f

View debug logs

backuphero-agent start --config /etc/backuphero/backuphero.json

Set logLevel: "debug" in your config file for verbose output.

Uninstall

# Stop the service
sudo systemctl stop backuphero-agent
sudo systemctl disable backuphero-agent

# Remove systemd service
sudo rm /etc/systemd/system/backuphero-agent.service
sudo systemctl daemon-reload

# Uninstall package
npm uninstall -g @backuphero.io/agent

# Remove configuration (optional)
sudo rm -rf /etc/backuphero

License

MIT - see LICENSE for details.

Support

• Documentation: https://docs.backuphero.io
• Email: [email protected]
• GitHub Issues: https://github.com/backuphero/agent/issues