Surge README

The project's README from github.com/SurgeDM/Surge. As one markdown file: README.md.

Surge

Blazing fast TUI download manager built in Go for power users

Ask DeepWiki Release Go Version License BuyMeACoffee Stars

Documentation • Installation • Usage • Themes • Fonts • Benchmarks • Extension • Settings • CLI Reference

What is Surge?

Surge is designed for power users who prefer a keyboard-driven workflow. It features a beautiful Terminal User Interface (TUI), as well as a background Headless Server and a CLI tool for automation.

Surge Demo

Why use Surge?

Most browsers open a single connection for a download. Surge opens multiple (up to 16 by default), splits the file, and downloads chunks in parallel. But we take it a step further:

For a deep dive into how we make downloads faster (like work stealing and slow worker handling), check out our Optimization Guide.

Support the Project

We are just two CS students building Surge in between classes and exams. We love working on this, but maintaining a project of this scale takes time and resources. That's where you come in!

If Surge saves you time, consider supporting the development! Donations go directly toward:

☕ Buy us a coffee

Totally optional-your stars, issues, and contributions already mean the world to us! :)

Installation

Surge is available on multiple platforms. Choose the method that works best for you.

Platform / Method Command / Instructions Notes
Prebuilt Binary Download from Releases Easiest method. Just download and run.
Linux AppImage Download from Releases Run chmod +x Surge_..._linux_x86_64.AppImage, then ./Surge_..._linux_x86_64.AppImage. Supports delta updates.
Arch Linux (AUR) yay -S surge Managed via AUR.
macOS / Linux (Homebrew) brew install SurgeDM/tap/surge Recommended for Mac/Linux users.
Nix / NixOS nix run github:SurgeDM/Surge Via Nix flake. NixOS config: inputs.surge.packages.${pkgs.system}.default
Windows winget install surge-downloader.surge
or
scoop install surge
or
choco install surge		 Recommended for Windows users.
Dockerfile See instructions Run Surge in server mode with Docker Compose
Go Install go install github.com/SurgeDM/Surge@latest Requires Go 1.25+

Usage

Surge has two main modes: TUI (Interactive) and Server (Headless).

For a full reference, see the customization guide, Settings & Configuration Guide and the CLI reference.

1. Interactive TUI Mode

Just run surge to enter the dashboard. This is where you can visualize progress, manage the queue, and see speed graphs. If you encounter any issues, press ? to open the bug reporting wizard. You can also press Shift + A or use your terminal's paste shortcut to automatically parse a copied browser 'cURL' command straight into a new download.

# 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

--no-server keeps the TUI fully local and skips the embedded HTTP API. CLI control commands such as surge add, surge pause, and browser-extension requests will not be able to target that instance.

2. Server Mode (Headless)

Great for servers, Raspberry Pis, or background processes.

# 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>

3. Auto-Start Service

Surge provides an official way to manage it as a system service (daemon). This is the recommended way for servers and reproducible deployments.

# Install Surge as a system service
surge service install

# Manage the service
surge service start
surge service stop
surge service status
surge service token

# Uninstall the service
surge service uninstall

[!NOTE] On Linux, these commands may require sudo. On Windows, they should be run in an elevated (Administrator) terminal.

4. Remote TUI

surge and surge server bind the HTTP API to 0.0.0.0 (all interfaces) by default. This means the server is accessible via localhost (127.0.0.1) as well as your local network IP.

The API is token-protected. Generate/read your token by running:

# Get the standard token
surge token

# Get the token if Surge is installed as a system service
surge service token

Alternatively, you can find it in the TUI under Settings > Extension.

3. Remote TUI

Connect to a running Surge daemon (local or remote).

# Connect to local server (auto-detected)
surge connect

# Connect to a remote daemon
surge connect 192.168.1.10:1700 --token <token>

# Equivalent global-flag form
surge --host 192.168.1.10:1700 --token <token>

By default, surge connect uses:

4. Global Connection Flags (CLI + TUI)

These global flags are available on all commands:

Environment variable fallbacks:

5. Server Mode with Docker Compose

Download the compose file and start the container:

wget https://raw.githubusercontent.com/SurgeDM/Surge/refs/heads/main/docker/compose.yml
docker compose up -d

Get the API token:

docker compose exec surge surge token

Save this token - you'll need it to authenticate API requests and connect remotely.

Check downloads/API availability:

docker compose exec surge surge ls

View logs:

docker compose logs -f surge

Fonts

Surge ships a bundled Nerd Font for the TUI, but your terminal controls the actual font selection. See the customization guide for install steps and licensing details.

Benchmarks

We tested Surge against standard tools. Because of our connection optimization logic, Surge significantly outperforms single-connection tools.

Tool Time Speed Comparison
Surge 28.93s 35.40 MB/s -
aria2c 40.04s 25.57 MB/s 1.38× slower
curl 57.57s 17.79 MB/s 1.99× slower
wget 61.81s 16.57 MB/s 2.14× slower

Test details: 1GB file, Windows 11, Ryzen 5 5600X, 360 Mbps Network. Results averaged over 5 runs.

We would love to see you benchmark Surge on your system!

To compare fixed and adaptive concurrency under deterministic throttling, run:

go test ./internal/strategy/concurrent -run '^$' -bench BenchmarkThrottle -benchtime=1x -count=5

The native Go benchmark runs persistent-overload and burst-recovery workloads with both policies and reports elapsed time, request amplification, throttled requests, and peak accepted concurrency.

Browser Extension

The Surge extension intercepts browser downloads and sends them straight to your terminal. It communicates with the Surge client on port 1700 by default.

[!IMPORTANT] An Auth Token is required to connect the extension to your Surge server. This can be obtained from the TUI under Settings > Extension, or by running surge token (or surge service token if installed as a system service).

Chrome / Edge / Brave

  1. Stable: Get the Extension from Chrome Web Store
  2. Development:
    • Download extension-chrome.zip from the latest GitHub release.
    • Unzip it somewhere on disk.
    • Open your browser and navigate to chrome://extensions.
    • Enable "Developer mode" in the top right corner.
    • Click "Load unpacked".
    • Select the unzipped extension-chrome folder.
    • Click the Surge icon in your browser toolbar and enter your Auth Token in the settings.

Firefox

  1. Stable: Get the Add-on
  2. Development:
    • Download extension-firefox.zip from the latest GitHub release.
    • Navigate to about:debugging#/runtime/this-firefox.
    • Click "Load Temporary Add-on...".
    • Select the zip file (or unzip and select manifest.json).
    • Click the Surge icon in your browser toolbar and enter your Auth Token in the settings.

Acknowledgements

Huge thanks to the teams and sponsors helping us build and ship Surge:

Community & Contributing

We love community contributions! Whether it's a bug fix, a new feature, or just cleaning up typos. PRs are always welcome. For a quick guide, see CONTRIBUTING.md.

You can check out the Discussions for any questions or ideas, or follow us on X (Twitter)!

License

Distributed under the MIT License. See LICENSE for more information.

Star History Chart
If Surge saved you some time, consider giving it a ⭐ to help others find it!

Surge (SurgeDM/Surge)

Searching Database…

3.6K ·GitHub
Surge
Что это?Surge — терминальный (TUI) менеджер загрузок, написанный на Go, для продвинутых пользователей, которым нужны быстрые, управляемые с клавиатуры загрузки с несколькими соединениями.
Surge — это просто терминальное приложение или оно также работает в фоне?Это три вещи сразу: интерактивная TUI-панель, фоновый Headless Server (демон) и CLI-инструмент для автоматизации — все они общаются с одним общим процессом-движком.
Как установить Surge?Скачайте готовый бинарник из Releases или используйте пакетный менеджер: brew install SurgeDM/tap/surge, winget install surge-downloader.surge / scoop / choco на Windows, yay -S surge на Arch или nix run github:SurgeDM/Surge. Можно также выполнить go install github.com/SurgeDM/Surge@latest.
Нужен ли установленный Go для работы?Нет, готовым бинарникам и установке через пакетные менеджеры ничего дополнительного не нужно; только метод 'go install' требует Go 1.25 или новее.
Безопасно ли оставлять удаленный сервер запущенным?По умолчанию HTTP API привязывается ко всем сетевым интерфейсам (0.0.0.0), а не только к localhost, так что он доступен из вашей локальной сети и защищен лишь bearer-токеном, а не полноценной аутентификацией.
Surge работает на Linux, macOS и Windows или только на одной платформе?Он поставляется с готовыми пакетами для Linux, macOS и Windows (через Homebrew, AUR, winget, scoop, choco, Nix или Docker) и рассчитан на работу без интерфейса (headless) на серверах и Raspberry Pi.
Как именно Surge ускоряет загрузки по сравнению с curl или wget?Он разбивает одну загрузку до 16 параллельных частей и может качать с нескольких зеркал одновременно, распределяя воркеров по источникам с автоматическим переключением, если одно зеркало медленное или недоступное.
Что делает браузерное расширение?Оно перехватывает загрузки, начатые в Chrome, Edge, Brave или Firefox, и пересылает их прямо в ваш терминальный клиент Surge через порт 1700 с аутентификацией токеном, сгенерированным Surge.
Насколько Surge быстрее других инструментов для загрузок?В собственном бенчмарке из README на файле 1 ГБ Surge выдал 35.40 МБ/с против aria2c (в 1.38 раза медленнее), curl (в 1.99 раза медленнее) и wget (в 2.14 раза медленнее).
Что такое Streaming Mode?Это опция загрузки фрагментов файла в строго последовательном порядке вместо параллельного — полезно для медиафайлов, которые хочется начать просматривать до завершения загрузки.
What are similar projects?hydra, Ketch, hister, FluxDown, Motrix, pinchtab, glances, kubo
Which topics is it in?download-manager, remote-access, firefox-extension, downloader, raspberry-pi, chrome-extension, browser-extension, tui, cli-tool, golang, dashboard, benchmark
Creator
SurgeDM
Size
44.2 MB
Stars
3.6K
Updated
CommitOct 10Releasev0.12.2Sep 22
Age
11mo
Commits · 90 Days