Skip to main content
Surge stores user preferences in a JSON configuration file. You can edit this file manually or use the built-in Settings UI in the TUI (press s to open).

​
Configuration File Location

The settings.json file is located in the application data directory: 
~/.config/surge/settings.json
# Or $XDG_CONFIG_HOME/surge/settings.json if set
If the file doesn’t exist, Surge will create it with default values on first run.

​
Directory Structure

Surge organizes its files according to OS conventions:
DirectoryPurposeLinuxmacOSWindows
Configsettings.json~/.config/surge/~/Library/Application Support/surge/%APPDATA%\surge\
StateDatabase (surge.db), auth token~/.local/state/surge/~/Library/Application Support/surge/%APPDATA%\surge\
LogsTimestamped .log files~/.local/state/surge/logs/~/Library/Application Support/surge/logs/%APPDATA%\surge\logs\
RuntimePID file, port file, lock$XDG_RUNTIME_DIR/surge/¹$TMPDIR/surge-runtime/%TEMP%\surge\
¹ Falls back to ~/.local/state/surge/ when $XDG_RUNTIME_DIR is not set (e.g., Docker/headless environments).

​
Settings Structure

The configuration file is organized into three main categories: 
{
  "general": { ... },
  "network": { ... },
  "performance": { ... }
}

​
General Settings

Application behavior and UI preferences.
​
general.default_download_dir
string
default:""
Default directory where new downloads are saved.If empty, defaults to:
  1. $XDG_DOWNLOAD_DIR (if set and exists)
  2. ~/Downloads (if exists)
  3. Current directory (fallback)
"default_download_dir": "/home/user/Downloads"
​
general.warn_on_duplicate
boolean
default:"true"
Show a warning when adding a download that already exists in the queue.Prevents accidentally downloading the same file multiple times.
"warn_on_duplicate": true
​
general.extension_prompt
boolean
default:"false"
Prompt for confirmation in the TUI when adding downloads via the browser extension.When true, downloads from the extension require manual approval in the TUI. When false, they’re automatically queued (unless warn_on_duplicate triggers).
"extension_prompt": false
In headless mode, this setting causes extension downloads to be rejected unless the extension sets skip_approval.
​
general.auto_resume
boolean
default:"false"
Automatically resume paused downloads when Surge starts.When enabled, all downloads with status paused will be resumed on startup.
"auto_resume": false
Override with --no-resume flag to temporarily disable auto-resume.
​
general.skip_update_check
boolean
default:"false"
Disable automatic check for new versions on startup.
"skip_update_check": false
​
general.clipboard_monitor
boolean
default:"true"
Watch the system clipboard for URLs and prompt to download them.When enabled, Surge monitors the clipboard and shows a prompt when a URL is detected.
"clipboard_monitor": true
​
general.theme
integer
default:"0"
UI theme preference.Values:
  • 0 - Adaptive (follows system theme)
  • 1 - Light
  • 2 - Dark
"theme": 0
​
general.log_retention_count
integer
default:"5"
Number of recent log files to keep.Older log files are automatically deleted on startup. Set to 0 to keep all logs.
"log_retention_count": 5

​
Network Settings

Connection and download behavior.
​
network.max_connections_per_host
integer
default:"32"
Maximum concurrent connections allowed to a single host.Valid range: 1-64Higher values increase download speed but may be throttled or blocked by some servers.
"max_connections_per_host": 32
​
network.max_concurrent_downloads
integer
default:"3"
Maximum number of downloads running simultaneously.Valid range: 1-10
"max_concurrent_downloads": 3
Changing this setting requires restarting Surge.
​
network.user_agent
string
default:""
Custom User-Agent string for HTTP requests.If empty, uses Surge’s default User-Agent. Some servers require specific User-Agent strings.
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
​
network.proxy_url
string
default:""
HTTP/HTTPS proxy URL for all downloads.If empty, uses system proxy settings.
"proxy_url": "http://127.0.0.1:8080"
Supported formats:
  • http://proxy.example.com:8080
  • https://proxy.example.com:8080
  • http://user:[email protected]:8080
​
network.sequential_download
boolean
default:"false"
Download file pieces in strict order (Streaming Mode).Useful for previewing media files before download completes, but may be slower than parallel downloading.
"sequential_download": false
​
network.min_chunk_size
integer
default:"2097152"
Minimum size of a download chunk in bytes.Default: 2097152 (2 MB)Larger chunks reduce overhead but may waste bandwidth if connections stall.
"min_chunk_size": 2097152
Value in bytes: 1048576 = 1 MB, 2097152 = 2 MB
​
network.worker_buffer_size
integer
default:"524288"
I/O buffer size per worker in bytes.Default: 524288 (512 KB)Affects memory usage and disk write performance.
"worker_buffer_size": 524288

​
Performance Settings

Advanced tuning for reliability and speed optimization.
​
performance.max_task_retries
integer
default:"3"
Number of times to retry a failed chunk before giving up.Helps recover from temporary network errors or server timeouts.
"max_task_retries": 3
​
performance.slow_worker_threshold
float
default:"0.3"
Restart workers slower than this fraction of the mean speed.Valid range: 0.0-1.0Example: 0.3 means workers performing at less than 30% of average speed are restarted.
"slow_worker_threshold": 0.3
​
performance.slow_worker_grace_period
duration
default:"5s"
Time to wait before checking a worker’s speed.Prevents premature restarts during connection establishment.
"slow_worker_grace_period": 5000000000
Value in nanoseconds: 5000000000 = 5 seconds
​
performance.stall_timeout
duration
default:"3s"
Restart workers that haven’t received data for this duration.Helps recover from stalled connections.
"stall_timeout": 3000000000
Value in nanoseconds: 3000000000 = 3 seconds
​
performance.speed_ema_alpha
float
default:"0.3"
Exponential moving average smoothing factor for speed calculation.Valid range: 0.0-1.0Lower values = smoother but slower to react to speed changes. Higher values = more responsive but noisier.
"speed_ema_alpha": 0.3

​
Example Configuration

settings.json
{
  "general": {
    "default_download_dir": "/home/user/Downloads",
    "warn_on_duplicate": true,
    "extension_prompt": false,
    "auto_resume": false,
    "skip_update_check": false,
    "clipboard_monitor": true,
    "theme": 0,
    "log_retention_count": 5
  },
  "network": {
    "max_connections_per_host": 32,
    "max_concurrent_downloads": 3,
    "user_agent": "",
    "proxy_url": "",
    "sequential_download": false,
    "min_chunk_size": 2097152,
    "worker_buffer_size": 524288
  },
  "performance": {
    "max_task_retries": 3,
    "slow_worker_threshold": 0.3,
    "slow_worker_grace_period": 5000000000,
    "stall_timeout": 3000000000,
    "speed_ema_alpha": 0.3
  }
}

​
Editing Settings

  1. Press s in the TUI to open Settings
  2. Navigate with arrow keys
  3. Press Enter to edit a value
  4. Changes are saved immediately

​
Via File Editor

  1. Open settings.json in your preferred editor
  2. Make changes following valid JSON syntax
  3. Save the file
  4. Restart Surge for changes to take effect
Invalid JSON will prevent Surge from loading settings. Always validate your JSON before saving.

​
Migration & Compatibility

On Linux, Surge automatically migrates configuration from the legacy flat layout (~/.config/surge/*) to the XDG-compliant structure on first run:
  • surge.db → ~/.local/state/surge/surge.db
  • token → ~/.local/state/surge/token
  • logs/ → ~/.local/state/surge/logs/
Settings remain at ~/.config/surge/settings.json.
Legacy “connections” and “chunks” sections in old configuration files are automatically migrated to the “network” section.