Docs: Backup agents

Backup agents

Enterprise-grade backup agents for full machine protection. Install agents on your servers for automated file-level, block-level, and image backups with deduplication.

v1.0.0Updated 2026-09-26

Preview: the agent installer isn't published yet

You can register machines and plan their jobs in the dashboard, but there is no agent program to install yet, so registered machines stay pending and run no backups. Until it ships, back up a machine with the CLI, a Docker sidecar or a database agent. The rest of this page describes the agent as designed.

Linux

Ubuntu, Debian, RHEL, CentOS

Windows

Server 2016+, Windows 10/11

macOS

Monterey 12+

Planned features

File-level backup with include/exclude patterns
Block-level backup with Changed Block Tracking (CBT)
Full image backup for bare-metal recovery
Incremental and differential backup modes
Global deduplication with content-addressable storage
In-flight compression (gzip, zstd, lz4)
Client-side encryption (AES-256)
Bandwidth throttling for production environments
Pre/post backup scripts
Centralized management from LOX dashboard

Quick start

1. Register agent in dashboard

First, register a new agent in the LOX dashboard:

1. Go to Dashboard → Backup Agents
2. Click Add Agent
3. Enter the hostname and select the operating system
4. Click Register Agent

2. Install agent on server

Not available yet: there is no installer to run. When it ships, the dashboard will show the exact command, with the agent UUID and token, under Install on each agent.

Backup jobs

After the agent is installed and online, create backup jobs from the dashboard or via API.

Job Types

Type	Description	Use Case
file	File-level backup with patterns	Documents, configs, home directories
block	Block-level with CBT	VMs, large databases, minimal transfer
image	Full disk/volume image	Bare-metal recovery, system migration
database	Application-aware database backup	MySQL, PostgreSQL, MongoDB with VSS

Backup modes

Mode	Description	Storage
full	Complete backup of all data	Highest (baseline)
incremental	Only changes since last backup	Lowest (requires chain)
differential	Changes since last full backup	Medium (only needs full)

Example: File backup job (API)

POST /api/v1/backup-jobs
{
  "agent_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Daily Web Files",
  "job_type": "file",
  "backup_mode": "incremental",
  "source_paths": [
    "/var/www",
    "/etc/nginx",
    "/etc/letsencrypt"
  ],
  "exclude_patterns": [
    "*.log",
    "*.tmp",
    "node_modules/",
    ".git/"
  ],
  "schedule_cron": "0 2 * * *",
  "retention_count": 30,
  "compression_enabled": true,
  "encryption_enabled": true
}

Job Configuration

Basic settings

Field	Type	Description
name	string	Job display name
job_type	file\|block\|image\|database	Backup type
backup_mode	full\|incremental\|differential	Backup mode (default: incremental)
source_paths	string[]	Paths/volumes to backup
schedule_cron	string	Cron expression (null = manual only)
retention_count	integer	Number of backups to retain (default: 7)

File patterns

Field	Description
exclude_patterns	Glob patterns to exclude (*.log, temp/, etc.)
include_patterns	Only include files matching these patterns

Advanced settings

Field	Default	Description
compression_enabled	true	Enable zstd compression
encryption_enabled	false	Enable AES-256 encryption
deduplication_enabled	true	Enable block-level deduplication
bandwidth_limit_mbps	null	Max upload bandwidth (null = unlimited)
pre_script	null	Script to run before backup
post_script	null	Script to run after backup

Restore options

Restore types

Type	Description
full	Restore entire backup to original or new location
file	Restore individual files or folders
volume	Restore entire volume (block/image backups)
instant	Mount backup as live volume (read-only)

Restore via API

# Full restore to original location
POST /api/v1/machine-backups/{backup_uuid}/restore
{
  "restore_type": "full",
  "overwrite_existing": true,
  "preserve_permissions": true
}

# Restore specific files
POST /api/v1/machine-backups/{backup_uuid}/restore
{
  "restore_type": "file",
  "target_path": "/tmp/restore",
  "selected_files": [
    "/etc/nginx/nginx.conf",
    "/var/www/html/index.php"
  ]
}

Agent configuration

Configuration file

The agent configuration is stored in:

Linux/macOS: /etc/lox-agent/config.yaml
Windows: C:\ProgramData\LOX Agent\config.yaml

# /etc/lox-agent/config.yaml
api_url: https://backlox.com/api
agent_uuid: 550e8400-e29b-41d4-a716-446655440000
registration_token: lox_agt_xxxxxxxxxxxxx

# Heartbeat interval (seconds)
heartbeat_interval: 60

# Log level: debug, info, warn, error
log_level: info

# Working directory for temp files
work_dir: /var/lib/lox-agent

# Max concurrent backup jobs
max_concurrent_jobs: 2

# Network settings
bandwidth_limit_mbps: 100
retry_count: 3
retry_delay_seconds: 30

Deduplication

The agent uses content-addressable storage with variable-size chunking for efficient deduplication:

Variable-size chunks (4KB - 4MB) using rolling hash
SHA-256 content addressing
Cross-job deduplication within tenant
Typical dedup ratio: 5:1 to 20:1

Storage efficiency

With deduplication enabled, incremental backups typically transfer only 1-5% of total data. A 100GB server with daily backups might use only 110GB total storage for 30 days of history.

Security

End-to-end encryption

When encryption is enabled, data is encrypted on the agent before transmission. LOX never sees your encryption keys - they stay on your server.

TLS 1.3 for all API communication
Token-based authentication per agent
Optional client-side AES-256-GCM encryption
Token rotation from dashboard

Monitoring

Agent health

The agent sends heartbeats every 60 seconds. An agent is marked offline if no heartbeat is received for 5 minutes.

Prometheus metrics

# Agent exposes metrics on :9100/metrics
lox_agent_backup_total{job="web-files",status="success"}
lox_agent_backup_total{job="web-files",status="failed"}
lox_agent_backup_duration_seconds{job="web-files"}
lox_agent_backup_size_bytes{job="web-files"}
lox_agent_backup_files_count{job="web-files"}
lox_agent_dedup_ratio{job="web-files"}
lox_agent_upload_speed_bytes_per_second
lox_agent_heartbeat_timestamp

Troubleshooting

Agent shows "Offline"

Check the agent service is running: systemctl status lox-agent. Verify network connectivity to backlox.com and check firewall rules for outbound HTTPS.

Backup job fails with permission error

The agent runs as root by default. If running as a different user, ensure it has read access to all source paths. For VSS backups on Windows, the service must run as SYSTEM.

Slow backup speed

Check if bandwidth limiting is configured. First backup is always slower due to full transfer. Subsequent incremental backups should be much faster.

Debug mode

Set log_level: debug in config.yaml and restart the agent. Logs are in /var/log/lox-agent/ (Linux) or Event Viewer (Windows).

Service management

Linux (systemd)

# Start/stop/restart
sudo systemctl start lox-agent
sudo systemctl stop lox-agent
sudo systemctl restart lox-agent

# View status
sudo systemctl status lox-agent

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

Windows

# PowerShell (Administrator)
Start-Service "LOX Backup Agent"
Stop-Service "LOX Backup Agent"
Restart-Service "LOX Backup Agent"

# View status
Get-Service "LOX Backup Agent"

← Cloud Snapshots Airgap Daemon →