---
sidebar_position: 4
title: Configuration Reference
description: All config.yaml server keys with defaults and matching environment variables.
---

# 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

```yaml title="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:

```yaml
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:

```yaml
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](../operations/upgrade-recovery) for a tested snapshot and rollback sequence.