Configuration Reference

BackupX loads ./config.yaml from the working directory by default. You can override the path with --config. Every key can also be set via a BACKUPX_ prefixed environment variable.

Full config reference

config.yaml

server:
  host: "0.0.0.0"             # BACKUPX_SERVER_HOST
  port: 8340                  # BACKUPX_SERVER_PORT
  mode: "release"             # release | debug
  external_url: ""            # BACKUPX_SERVER_EXTERNAL_URL — stable public Master URL
  trusted_proxies:             # BACKUPX_SERVER_TRUSTED_PROXIES — exact proxy IPs/CIDRs
    - "127.0.0.1"
    - "::1"
  web_root: ""                # BACKUPX_SERVER_WEB_ROOT — built frontend directory

database:
  path: "./data/backupx.db"   # BACKUPX_DATABASE_PATH — embedded SQLite

security:
  jwt_secret: ""              # BACKUPX_SECURITY_JWT_SECRET — auto-generated if empty
  jwt_expire: "24h"           # BACKUPX_SECURITY_JWT_EXPIRE
  encryption_key: ""          # AES-256-GCM key for storage config encryption

backup:
  temp_dir: "/tmp/backupx"    # BACKUPX_BACKUP_TEMP_DIR
  max_concurrent: 2           # BACKUPX_BACKUP_MAX_CONCURRENT
  retries: 10                 # Per-upload rclone low-level retries
  bandwidth_limit: ""         # e.g. "10M" to cap transfers at 10 MB/s

log:
  level: "info"               # debug | info | warn | error
  file: "./data/backupx.log"
  max_size: 100               # MB per log file
  max_backups: 3              # rotated files retained
  max_age: 30                 # retention in days

Secret generation

If jwt_secret or encryption_key is empty on first start, BackupX generates a random value and persists it to the system_configs table. Keep a backup of data/backupx.db — losing it invalidates all existing encrypted storage configurations.

Environment variables

The environment wins when both file and env are set. All dot-paths become underscores and uppercase:

Config key	Env variable
server.port	BACKUPX_SERVER_PORT
server.external_url	BACKUPX_SERVER_EXTERNAL_URL
server.trusted_proxies	BACKUPX_SERVER_TRUSTED_PROXIES (comma-separated for env)
security.jwt_secret	BACKUPX_SECURITY_JWT_SECRET
security.jwt_expire	BACKUPX_SECURITY_JWT_EXPIRE
security.encryption_key	BACKUPX_SECURITY_ENCRYPTION_KEY
log.level	BACKUPX_LOG_LEVEL
backup.max_concurrent	BACKUPX_BACKUP_MAX_CONCURRENT
backup.temp_dir	BACKUPX_BACKUP_TEMP_DIR
backup.retries	BACKUPX_BACKUP_RETRIES
backup.bandwidth_limit	BACKUPX_BACKUP_BANDWIDTH_LIMIT
log.max_size	BACKUPX_LOG_MAX_SIZE
log.max_backups	BACKUPX_LOG_MAX_BACKUPS
log.max_age	BACKUPX_LOG_MAX_AGE

Master external URL

Set server.external_url when BackupX is behind Docker, Nginx, a load balancer, or any reverse proxy whose internal Host is not reachable by remote Agents:

server:
  external_url: "https://backup.example.com"

This value is used when BackupX renders one-click Agent install scripts and docker-compose snippets. It must be reachable from every Agent host. Leave it empty only when X-Forwarded-Proto / X-Forwarded-Host are reliable and point to the same URL that Agents can access.

The install wizard can set an Agent-specific URL for a proxy or SSH-bastion node. That override is used by both the target-side one-time install URL and the generated Agent runtime configuration, while the browser continues to use the normal public address.

Trusted reverse proxies

BackupX trusts forwarded client-address headers only from server.trusted_proxies. The default permits loopback Nginx only. If a reverse proxy runs in another container or host, add its exact IP or subnet:

server:
  trusted_proxies:
    - "127.0.0.1"
    - "172.18.0.0/16"

Do not configure 0.0.0.0/0: client addresses feed authentication throttling, install-token throttling, and audit records. Set an empty list when BackupX is exposed directly and should trust no forwarded headers.

Back up the complete data directory and configuration before changing security keys or database paths. See Upgrade and Recovery for a tested snapshot and rollback sequence.