DOCSEARCHbyAlgolia
Submit Docs

Surge Download Manager

repository·main·Indexed 25 days ago

https://github.com/surgedm/surge

A high-performance, keyboard-driven download manager built in Go. Surge features a TUI, a headless server mode, and a CLI for automation, utilizing parallel chunked downloads to maximize bandwidth. It includes a dedicated HTTP API for remote management, support for custom download categories, and browser extensions for Chrome, Edge, Brave, and Firefox.

Tokens
16.4K
Snippets
27
Records
122
Agent score
86%

What's inside Surge

  1. Understand Surge download optimization strategies

    main

    Surge maximizes download speeds by using multiple concurrent HTTP connections (up to 32) to bypass single-connection bandwidth limits imposed by servers. It employs several strategies to handle connection variability caused by load balancers and CDNs:

    • Large chunks: Files are split into $num_workers parts, assigning each worker (fileSize/num_workers) bytes to ensure efficient, large-scale transfers.
    • HealthCheck: Surge monitors the mean speed of all workers. If a worker's speed drops below 0.3x of the mean, Surge restarts that worker to attempt to establish a faster pathway to the server.
    • StealWork: When fast workers finish their assigned chunks while slow workers are still active, idle workers 'steal' work from the remaining slow workers to balance the load.
    • HedgeWork: When chunk sizes become too small for StealWork, Surge uses a hedging strategy. An idle worker is assigned the same task as an active worker. If the idle worker completes the task first, Surge uses its result and cancels the original active worker's task.

  3. Use Interactive TUI Mode

    main

    The Interactive TUI (Terminal User Interface) allows you to visualize progress, manage the download queue, and view speed graphs. Use the following commands to start the TUI:

    • surge: Starts the standard TUI with the local HTTP API server enabled.
    • surge --no-server: Starts the TUI without the embedded HTTP API. Note that CLI control commands (like surge add) and browser extensions will not work in this mode.
    • surge <URL1> <URL2> ...: Starts the TUI with specific URLs already queued.
    • surge <URL> --batch <file>: Starts the TUI and queues URLs listed in a batch file.
    # Start the TUI
surge

# Start the TUI without the local HTTP API server
surge --no-server

# Start TUI with downloads queued
surge https://example.com/file1.zip https://example.com/file2.zip

# Combine URLs and batch file
surge https://example.com/file.zip --batch urls.txt

  4. Install and Configure the Surge Browser Extension

    main

    The Surge extension intercepts browser downloads and sends them to the Surge client on port 1700 by default. An Auth Token is required.

    Obtaining the Auth Token:

    • In the TUI: Settings > Extension
    • Via CLI: surge token (or surge service token if using the system service).

    Installation for Chrome / Edge / Brave:

    1. Stable: Install from the Chrome Web Store.
    2. Development:
      • Download extension-chrome.zip from GitHub releases.
      • Unzip and go to chrome://extensions.
      • Enable "Developer mode".
      • Click "Load unpacked" and select the unzipped folder.
      • Enter your Auth Token in the extension settings.

    Installation for Firefox:

    1. Stable: Get the add-on from Firefox Add-ons.
    2. Development:
      • Download extension-firefox.zip from GitHub releases.
      • Navigate to about:debugging#/runtime/this-firefox.
      • Click "Load Temporary Add-on..." and select the zip or manifest.json.
      • Enter your Auth Token in the extension settings.

  5. Install the bundled Nerd Font for Surge

    main

    To ensure a consistent TUI look and proper glyph coverage in Surge, you should install the bundled JetBrains Mono Nerd Font Mono. Surge cannot force a terminal font; you must install the font on your system and manually select it in your terminal emulator settings.

    1. Download fonts.zip from the latest GitHub release.
    2. Unzip the file.
    3. Follow the installation steps for your operating system below.
    4. Set your terminal emulator's font to JetBrainsMono Nerd Font Mono.
    # OS-specific installation steps

### macOS
1. Unzip `fonts.zip`.
2. Double-click the TTF files and click **Install** in Font Book.
3. Set your terminal font to `JetBrainsMono Nerd Font Mono`.

### Linux
1. Unzip `fonts.zip`.
2. Copy the TTF files to `~/.local/share/fonts/` (or `~/.fonts/`).
3. Run `fc-cache -f`.
4. Set your terminal font to `JetBrainsMono Nerd Font Mono`.

### Windows
1. Unzip `fonts.zip`.
2. Right-click each TTF file and choose **Install**.
3. Set your terminal font to `JetBrainsMono Nerd Font Mono`.

  6. Launch Surge in TUI or Server Mode

    main

    Surge can be run in two primary modes: an interactive Terminal User Interface (TUI) or a headless server mode.

    • TUI Mode: Use surge [url]... to launch the interactive interface. You can queue optional URLs to be downloaded immediately upon startup.
    • Server Mode: Use surge server [url]... to launch a headless server. This is the primary command for background automation.

    Key Flags:

    • --batch, -b: Enables batch processing.
    • --port, -p: Specifies the port to listen on.
    • --output, -o: Sets the download directory (defaults to Current Working Directory).
    • --no-resume: Disables resuming existing downloads.
    • --exit-when-done: Automatically exits the process once all queued URLs are processed.
    • --no-server: (TUI mode only) Disables the embedded HTTP API for that session.
    • --token: (Server mode only) Sets the API authentication token.

  7. Use Server Mode (Headless)

    main

    Server mode is ideal for background processes, servers, or Raspberry Pis. It runs without a TUI.

    • surge server: Starts the headless server.
    • surge server <URL>: Starts the server and immediately queues a download.
    • surge server --token <token>: Starts the server with a specific API token.
    # Start the server
surge server

# Start the server with a download
surge server https://url.com/file.zip

# Start with explicit API token
surge server --token <token>

  8. Customize keyboard shortcuts via keymap.json

    main

    Surge allows keyboard shortcut customization by editing the keymap.json file. This file is automatically generated on the first startup and is structured into nested sections corresponding to TUI states (e.g., dashboard, settings, file_picker). Each binding requires a keys array and a help description.

    File Locations:

    • Windows: %APPDATA%\surge\keymap.json
    • macOS: ~/Library/Application Support/surge/keymap.json
    • Linux: ~/.config/surge/keymap.json

    Note on Quit vs ForceQuit:

    • Quit (ctrl+c or ctrl+q): Performs a graceful shutdown, persisting progress and state.
    • ForceQuit (ctrl+c): Performs an immediate exit without waiting for the background engine. To avoid ambiguity, you may wish to bind them to different keys.
    {
  "dashboard": {
    "Quit": {
      "keys": [
        "ctrl+c",
        "ctrl+q"
      ],
      "help": "quit"
    },
    "Up": {
      "keys": [
        "up",
        "k"
      ],
      "help": "up"
    }
  }
}

  9. Connect to a Remote Surge Server

    main

    To interact with a running Surge server from a different machine or terminal session, use the connect command.

    • Command: surge connect [host:port]
    • Usage: This launches a TUI that is connected to the specified remote server. If no target is provided, it attempts to auto-detect a local server.
    • Flag: --insecure-http allows connecting over unencrypted HTTP.

  10. Install Surge

    main

    Surge can be installed on various platforms using the following methods:

    • Prebuilt Binary: Download from the GitHub Releases page.
    • Arch Linux (AUR): yay -S surge
    • macOS / Linux (Homebrew): brew install SurgeDM/tap/surge
    • Nix / NixOS: nix run github:SurgeDM/Surge
    • Windows: winget install surge-downloader.surge or scoop install surge
    • Go Install: go install github.com/SurgeDM/Surge@latest (Requires Go 1.25+)
    go install github.com/SurgeDM/Surge@latest

  11. Run Surge with Docker Compose

    main

    To run Surge in server mode using Docker Compose:

    1. Download the compose file: wget https://raw.githubusercontent.com/SurgeDM/Surge/refs/heads/main/docker/compose.yml
    2. Start the container: docker compose up -d
    3. Retrieve the API token: docker compose exec surge surge token
    4. Check downloads/API availability: docker compose exec surge surge ls
    5. View logs: docker compose logs -f surge

  12. Locate Surge theme files

    main

    Surge resolves themes using the following priority order:

    1. Direct Path / Working Directory: A full path or a filename located in your current working directory.
    2. Local themes/ Folder: A directory named themes/ relative to the Surge execution path.
    3. Global Surge Themes: The user configuration directory:
      • Linux: ~/.config/surge/themes/
      • macOS: ~/Library/Application Support/surge/themes/
      • Windows: %APPDATA%\surge\themes/