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:- Intercepts the download before the browser starts it
- Cancels the browser’s single-connection download
- Sends the URL to Surge for parallel multi-connection download
- 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
Load unpacked extension
Click Load unpacked and select the
extension-chrome folder from the Surge directory.Firefox Installation
- Stable (Recommended)
- Development
Install the official Firefox add-on:
- Visit the Firefox Add-on page
- Click Add to Firefox
- Approve the permissions
Extension Configuration
Click the Surge extension icon to open the popup:Check connection status
The popup displays:
- Online: Surge is running and accessible
- Offline: Cannot connect to Surge server
Enable/disable interception
Toggle the Intercept Downloads switch to control whether downloads are sent to Surge.
Configure authentication token
If your Surge server requires authentication:
- Get your token:
surge token - Paste it in the Auth Token field
- 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)
Duplicate Detection
The extension checks if a URL is already being downloaded by Surge:- If duplicate detected, prompts you to confirm or skip
- Prevents accidentally queueing the same file multiple times
- 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:Extension Permissions
The extension requires these permissions:| Permission | Purpose |
|---|---|
downloads | Intercept and cancel browser downloads |
storage | Save settings (server URL, token, intercept state) |
notifications | Show download start/complete notifications |
webRequest | Capture 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
Troubleshooting
Downloads not intercepting
- Check that Intercept Downloads is enabled in the popup
- Verify Surge is running on the correct port
- Check browser console for errors (F12 → Console)
Authentication errors
If you see 401/403 errors:
- Get your token:
surge token - Enter it in the extension popup
- Click Save and verify it shows “Token valid”
Remote Server Configuration
To use the extension with a remote Surge server:Configure extension
In the extension popup:
- Server URL:
http://192.168.1.10:1700 - Auth Token:
<token-from-server> - Click Save
Advanced Configuration
Custom Server Discovery
The extension scans ports 1700-1800 to find your Surge instance:extension-chrome/background.js (excerpt)
Extension Prompt Mode
You can configure Surge to prompt for confirmation before accepting extension downloads:Keyboard Shortcuts
Set custom keyboard shortcuts for the extension:- Navigate to
chrome://extensions/shortcuts - Find Surge Download Manager
- Set shortcuts for:
- Open popup
- Toggle interception