Skip to main content
The Surge browser extension intercepts downloads from Chrome, Edge, Brave, and Firefox, sending them straight to your Surge client for accelerated multi-connection downloads.

How It Works

The extension communicates with your local Surge instance on port 1700 by default. When you download a file in your browser, the extension:
  1. Intercepts the download before the browser starts it
  2. Cancels the browser’s single-connection download
  3. Sends the URL to Surge for parallel multi-connection download
  4. Optionally captures authentication headers for protected downloads
The extension requires a running Surge instance (TUI or server mode) on your local machine or network.

Chrome / Edge / Brave Installation

1

Download the extension

Clone or download the Surge repository:
git clone https://github.com/surge-downloader/surge.git
cd surge
2

Open extensions page

Navigate to chrome://extensions in your browser.
3

Enable Developer mode

Toggle Developer mode in the top right corner.
4

Load unpacked extension

Click Load unpacked and select the extension-chrome folder from the Surge directory.
5

Verify installation

You should see the Surge icon in your browser toolbar.
The Chrome extension is not yet published to the Chrome Web Store. You need to install it manually using Developer mode.

Firefox Installation

Extension Configuration

Click the Surge extension icon to open the popup:
1

Check connection status

The popup displays:
  • Online: Surge is running and accessible
  • Offline: Cannot connect to Surge server
2

Enable/disable interception

Toggle the Intercept Downloads switch to control whether downloads are sent to Surge.
3

Configure authentication token

If your Surge server requires authentication:
  1. Get your token: surge token
  2. Paste it in the Auth Token field
  3. Click Save
4

Set custom server URL (optional)

If Surge is running on a different port or remote server:
  1. Enter the server URL (e.g., http://192.168.1.10:1700)
  2. Click Save

Extension Features

Download Interception

When enabled, the extension automatically:
  • Intercepts browser downloads
  • Sends them to Surge for acceleration
  • Shows notifications when downloads start
  • Opens the extension popup to show progress

Header Capture

The extension captures request headers (cookies, authorization, etc.) and forwards them to Surge. This enables downloading from authenticated sources:
extension-chrome/background.js (excerpt)
chrome.webRequest.onBeforeSendHeaders.addListener(
  (details) => {
    const headers = {};
    for (const header of details.requestHeaders) {
      headers[header.name] = header.value;
    }
    capturedHeaders.set(details.url, {
      headers,
      timestamp: Date.now(),
    });
  },
  { urls: ["<all_urls>"] },
  ["requestHeaders", "extraHeaders"]
);
Headers are cached for 2 minutes to support downloads from authenticated endpoints.

Duplicate Detection

The extension checks if a URL is already being downloaded by Surge:
  1. If duplicate detected, prompts you to confirm or skip
  2. Prevents accidentally queueing the same file multiple times
  3. Shows pending duplicates as a badge on the extension icon

Live Progress Tracking

The extension popup displays:
  • Active downloads with real-time progress
  • Download speed (MB/s)
  • Estimated time remaining (ETA)
  • Pause/Resume/Cancel controls

Port Configuration

The extension defaults to port 1700. If Surge is running on a different port:
surge server --port 8080

Extension Permissions

The extension requires these permissions:
PermissionPurpose
downloadsIntercept and cancel browser downloads
storageSave settings (server URL, token, intercept state)
notificationsShow download start/complete notifications
webRequestCapture request headers for authenticated downloads
<all_urls>Access headers for any download URL
The extension only communicates with your local Surge instance. No data is sent to external servers.

Manifest (Chrome/Edge)

extension-chrome/manifest.json
{
  "manifest_version": 3,
  "name": "Surge Download Manager",
  "version": "1.6.5",
  "description": "High-performance download acceleration with live progress tracking.",
  "permissions": ["downloads", "storage", "notifications", "webRequest"],
  "host_permissions": ["http://127.0.0.1/*", "<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  }
}

Troubleshooting

1

Extension shows 'Offline'

Ensure Surge is running:
surge
Or in server mode:
surge server
2

Downloads not intercepting

  1. Check that Intercept Downloads is enabled in the popup
  2. Verify Surge is running on the correct port
  3. Check browser console for errors (F12 → Console)
3

Authentication errors

If you see 401/403 errors:
  1. Get your token: surge token
  2. Enter it in the extension popup
  3. Click Save and verify it shows “Token valid”
4

Port conflicts

If port 1700 is in use:
surge server --port 1701
Update extension Server URL to http://localhost:1701

Remote Server Configuration

To use the extension with a remote Surge server:
1

Get the server token

On the remote server:
surge token
2

Configure extension

In the extension popup:
  • Server URL: http://192.168.1.10:1700
  • Auth Token: <token-from-server>
  • Click Save
3

Test connection

The status indicator should show Online if successful.
Using HTTP for remote servers sends your token in plaintext. Use a VPN or SSH tunnel for secure remote access.

Advanced Configuration

Custom Server Discovery

The extension scans ports 1700-1800 to find your Surge instance:
extension-chrome/background.js (excerpt)
const DEFAULT_PORT = 1700;
const MAX_PORT_SCAN = 100;

for (let port = DEFAULT_PORT; port < DEFAULT_PORT + MAX_PORT_SCAN; port++) {
  const url = `http://127.0.0.1:${port}`;
  const response = await fetch(`${url}/health`, {
    signal: AbortSignal.timeout(200),
  });
  if (response.ok) {
    const data = await response.json();
    if (data.status === "ok") {
      return url;
    }
  }
}

Extension Prompt Mode

You can configure Surge to prompt for confirmation before accepting extension downloads:
# In Surge TUI
Settings General Extension Prompt: true
This adds an extra confirmation step in the TUI before queuing downloads.

Keyboard Shortcuts

Set custom keyboard shortcuts for the extension:
  1. Navigate to chrome://extensions/shortcuts
  2. Find Surge Download Manager
  3. Set shortcuts for:
    • Open popup
    • Toggle interception
Use Ctrl+Shift+S to quickly toggle download interception on/off.