Configuration

Configuration is loaded from three sources, in order of priority (highest first):

  1. CLI flags -- passed directly to the command
  2. Config file -- ~/.roxyproxy/config.json
  3. Built-in defaults

CLI flags always win. Values not set on the command line fall back to the config file, and anything not in the config file uses the built-in default.

Config File

Create ~/.roxyproxy/config.json:

{
  "proxyPort": 8080,
  "uiPort": 8081,
  "dbPath": "~/.roxyproxy/data.db",
  "maxAge": "7d",
  "maxDbSize": "500MB",
  "maxBodySize": "1MB",
  "certCacheSize": 500
}

Options

Field Default Description
proxyPort 8080 Proxy listening port
uiPort 8081 Web UI and REST API port
dbPath ~/.roxyproxy/data.db SQLite database file path (supports ~)
maxAge 7d Auto-delete requests older than this
maxDbSize 500MB Auto-delete oldest requests when DB exceeds this size
maxBodySize 1MB Truncate request/response bodies larger than this
certCacheSize 500 Max per-domain SSL certificates cached in memory

Size and Duration Formats

Sizes accept raw bytes (1048576) or human-readable units (1KB, 10MB, 1GB).

Durations accept raw milliseconds (86400000) or human-readable units (1s, 5m, 1h, 7d).

Auto-Cleanup

A background job runs every 5 minutes to enforce maxAge and maxDbSize:

  • Deletes requests older than maxAge
  • If the database still exceeds maxDbSize, deletes the oldest requests in batches
  • Runs incremental vacuum to reclaim disk space

This means you can leave RoxyProxy running indefinitely without worrying about disk usage. The defaults (7 days, 500 MB) keep a useful history window while staying lightweight.

← REST API HTTPS Interception →