Configuration

Surge stores its configuration in a JSON file and follows OS conventions for directory structure. You can access settings through the TUI or edit the configuration file directly.

Configuration File

The settings.json file location varies by platform:

Linux
macOS
Windows

~/.config/surge/settings.json

Respects $XDG_CONFIG_HOME if set.

~/Library/Application Support/surge/settings.json

%APPDATA%\surge\settings.json

You can edit settings in the TUI by pressing s or by directly modifying the JSON file. Changes take effect after restarting Surge.

Directory Structure

Surge follows OS conventions for storing its files:

Directory	Purpose	Linux	macOS	Windows
Config	`settings.json`	`~/.config/surge/`	`~/Library/Application Support/surge/`	`%APPDATA%\surge\`
State	Database (`surge.db`), auth token	`~/.local/state/surge/`	`~/Library/Application Support/surge/`	`%APPDATA%\surge\`
Logs	Timestamped `.log` files	`~/.local/state/surge/logs/`	`~/Library/Application Support/surge/logs/`	`%APPDATA%\surge\logs\`
Runtime	PID 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).

General Settings

These settings control application behavior:

Key	Type	Description	Default
`default_download_dir`	string	Directory where new downloads are saved. If empty, defaults to `~/Downloads` or current directory.	`""`
`warn_on_duplicate`	bool	Show a warning when adding a download that already exists in the list.	`true`
`extension_prompt`	bool	Prompt for confirmation in the TUI when adding downloads via the browser extension.	`false`
`auto_resume`	bool	Automatically resume paused downloads when Surge starts.	`false`
`skip_update_check`	bool	Disable automatic check for new versions on startup.	`false`
`clipboard_monitor`	bool	Watch the system clipboard for URLs and prompt to download them.	`true`
`theme`	int	UI Theme (0=Adaptive, 1=Light, 2=Dark).	`0`
`log_retention_count`	int	Number of recent log files to keep.	`5`

Theme Values

internal/config/settings.go (excerpt)

const (
    ThemeAdaptive = 0  // Follows terminal color scheme
    ThemeLight    = 1  // Light mode
    ThemeDark     = 2  // Dark mode
)

Example Configuration

{
  "general": {
    "default_download_dir": "/home/user/Downloads",
    "warn_on_duplicate": true,
    "extension_prompt": false,
    "auto_resume": true,
    "skip_update_check": false,
    "clipboard_monitor": true,
    "theme": 2,
    "log_retention_count": 10
  }
}

Connection Settings

These settings control network connections and download behavior:

Key	Type	Description	Default
`max_connections_per_host`	int	Maximum concurrent connections allowed to a single host (1-64).	`32`
`max_concurrent_downloads`	int	Maximum number of downloads running simultaneously (requires restart).	`3`
`user_agent`	string	Custom User-Agent string for HTTP requests. Leave empty for default.	`""`
`proxy_url`	string	HTTP/HTTPS proxy URL (e.g., `http://127.0.0.1:8080`). Leave empty to use system settings.	`""`
`sequential_download`	bool	Download file pieces in strict order (Streaming Mode). Useful for previewing media but may be slower.	`false`
`min_chunk_size`	int64	Minimum size of a download chunk in bytes (e.g., `2097152` for 2MB).	`2097152` (2MB)
`worker_buffer_size`	int	I/O buffer size per worker in bytes (e.g., `524288` for 512KB).	`524288` (512KB)

Default Values from Code

internal/config/settings.go (excerpt)

const (
    KB = 1024
    MB = 1024 * KB
)

Network: NetworkSettings{
    MaxConnectionsPerHost:  32,
    MaxConcurrentDownloads: 3,
    UserAgent:              "",  // Empty means use default UA
    SequentialDownload:     false,
    MinChunkSize:           2 * MB,
    WorkerBufferSize:       512 * KB,
}

Changing max_concurrent_downloads requires restarting Surge for the setting to take effect.

Sequential Download (Streaming Mode)

Enable this for media files you want to preview while downloading:

{
  "network": {
    "sequential_download": true
  }
}

This downloads chunks in order, allowing media players to start playback before the download completes.

For maximum speed, keep sequential_download disabled. Enable it only when you need in-order chunks.

Performance Settings

These settings control performance tuning and optimization:

Key	Type	Description	Default
`max_task_retries`	int	Number of times to retry a failed chunk before giving up.	`3`
`slow_worker_threshold`	float	Restart workers slower than this fraction of the mean speed (0.0-1.0).	`0.3`
`slow_worker_grace_period`	duration	Time to wait before checking a worker’s speed (e.g., `5s`).	`5s`
`stall_timeout`	duration	Restart workers that haven’t received data for this duration (e.g., `3s`).	`3s`
`speed_ema_alpha`	float	Exponential moving average smoothing factor for speed calculation (0.0-1.0).	`0.3`

Default Values from Code

internal/config/settings.go (excerpt)

Performance: PerformanceSettings{
    MaxTaskRetries:        3,
    SlowWorkerThreshold:   0.3,
    SlowWorkerGracePeriod: 5 * time.Second,
    StallTimeout:          3 * time.Second,
    SpeedEmaAlpha:         0.3,
}

Work Stealing and Slow Workers

Surge automatically detects and restarts slow workers:

Slow Worker Threshold: Workers performing below 30% of the mean speed are restarted
Grace Period: Workers get 5 seconds before speed checks begin
Stall Timeout: Workers with no data for 3 seconds are restarted

For more details, see the Optimization Guide.

Complete Configuration Example

{
  "general": {
    "default_download_dir": "/home/user/Downloads",
    "warn_on_duplicate": true,
    "extension_prompt": false,
    "auto_resume": true,
    "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

TUI
JSON File

Open settings

Press s in the TUI to open the settings panel.

Navigate categories

Use tabs to switch between General, Network, and Performance settings.

Edit values

Select a setting and press Enter to edit. Type the new value and confirm.

Save

Press Ctrl+S to save changes, or Esc to cancel.

Open the file

# Linux/macOS
nano ~/.config/surge/settings.json

# Windows
notepad %APPDATA%\surge\settings.json

Edit values

Modify the JSON directly. Ensure valid JSON syntax.

Save and restart

Save the file and restart Surge for changes to take effect.

Environment-Specific Configuration

{
  "general": {
    "default_download_dir": "/mnt/storage/downloads",
    "auto_resume": true,
    "clipboard_monitor": false
  },
  "network": {
    "max_connections_per_host": 64,
    "max_concurrent_downloads": 5
  }
}

Resetting to Defaults

To reset all settings to defaults:

Stop Surge

surge server stop

Remove settings file

# Linux/macOS
rm ~/.config/surge/settings.json

# Windows
del %APPDATA%\surge\settings.json

Restart Surge

surge

Surge will recreate the settings file with defaults.

Migration (Linux XDG)

On Linux, Surge automatically migrates files from the old flat layout to XDG-compliant directories:

internal/config/paths.go (excerpt)

// Old location: ~/.config/surge/surge.db
// New location: ~/.local/state/surge/surge.db

// Old location: ~/.config/surge/token
// New location: ~/.local/state/surge/token

// Old location: ~/.config/surge/logs/
// New location: ~/.local/state/surge/logs/

This migration happens automatically on first run.

On macOS and Windows, all files remain in the application support directory - no migration needed.

Advanced: Runtime Config

Surge converts user settings to a runtime configuration for the download engine:

internal/config/settings.go (excerpt)

type RuntimeConfig struct {
    MaxConnectionsPerHost int
    UserAgent             string
    ProxyURL              string
    SequentialDownload    bool
    MinChunkSize          int64
    WorkerBufferSize      int
    MaxTaskRetries        int
    SlowWorkerThreshold   float64
    SlowWorkerGracePeriod time.Duration
    StallTimeout          time.Duration
    SpeedEmaAlpha         float64
}

This internal config is created from settings.json when Surge starts.

Get Started

Core Concepts

Guides

Advanced

Configuration

Configuration File

Directory Structure

General Settings

Theme Values

Example Configuration

Connection Settings

Default Values from Code

Sequential Download (Streaming Mode)

Performance Settings

Default Values from Code

Work Stealing and Slow Workers

Complete Configuration Example

Editing Settings

Environment-Specific Configuration

Resetting to Defaults

Migration (Linux XDG)

Advanced: Runtime Config

Get Started

Core Concepts

Guides

Advanced

​Configuration File

​Directory Structure

​General Settings

​Theme Values

​Example Configuration

​Connection Settings

​Default Values from Code

​Sequential Download (Streaming Mode)

​Performance Settings

​Default Values from Code

​Work Stealing and Slow Workers

​Complete Configuration Example

​Editing Settings

​Environment-Specific Configuration

​Resetting to Defaults

​Migration (Linux XDG)

​Advanced: Runtime Config

Configuration File

Directory Structure

General Settings

Theme Values

Example Configuration

Connection Settings

Default Values from Code

Sequential Download (Streaming Mode)

Performance Settings

Default Values from Code

Work Stealing and Slow Workers

Complete Configuration Example

Editing Settings

Environment-Specific Configuration

Resetting to Defaults

Migration (Linux XDG)

Advanced: Runtime Config