Skip to main content
Surge’s server mode runs a headless daemon perfect for servers, Raspberry Pis, or background processes. The server provides an HTTP API for managing downloads remotely.

​
Starting the Server

1

Launch the server

Start Surge in headless server mode:
surge server
This starts the background daemon with the HTTP API bound to 0.0.0.0:1700.
2

Queue downloads on startup

Start the server with initial downloads:
surge server https://url.com/file.zip
3

Use custom API token

Set an explicit authentication token:
surge server --token your-secure-token

​
Server Configuration

The server accepts several configuration flags: 
surge server --port 8080
The surge and surge server commands both 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.

​
API Authentication

The Surge server API is token-protected for security.

​
Getting Your Token

Retrieve the current API authentication token: 
surge token
This displays the token you need for API requests and remote connections.

​
Using Custom Tokens

Set a custom token when starting the server: 
surge server --token my-custom-token-here
Keep your API token secure. Anyone with the token can control your downloads and access the Surge API.

​
Exit When Done

The --exit-when-done flag is perfect for automation and scripting:
Download a file and exit when complete:
surge server --exit-when-done https://example.com/file.zip
The server will automatically shut down after the download finishes.

​
Managing the Server

​
Server Subcommands

Surge provides legacy compatibility commands for managing the server:
1

Start server

surge server start
Equivalent to surge server.
2

Stop server

surge server stop
Stops a running server process by PID file.
3

Check status

surge server status
Prints running/not-running status from PID/port state.

​
Checking Downloads

List all downloads via CLI: 
surge ls
Watch downloads in real-time: 
surge ls --watch
Get JSON output for scripting: 
surge ls --json

​
Network Binding

By default, Surge binds to all network interfaces:
  • Localhost Access: http://127.0.0.1:1700
  • Local Network: http://<your-ip>:1700
  • Remote Access: Configure firewall rules to allow external access
Use the --port flag to change the default port (1700) if it conflicts with other services.

​
Automation Examples

# /etc/systemd/system/surge.service
[Unit]
Description=Surge Download Manager
After=network.target

[Service]
Type=simple
User=surge
ExecStart=/usr/local/bin/surge server
Restart=on-failure

[Install]
WantedBy=multi-user.target

​
API Endpoints

The server exposes an HTTP API on port 1700:
EndpointMethodDescription
/healthGETHealth check (returns {"status": "ok"})
/listGETList all downloads
/downloadPOSTQueue a new download
/pause?id=<id>POSTPause a download
/resume?id=<id>POSTResume a download
/delete?id=<id>DELETEDelete a download
All API requests (except /health) require the Authorization: Bearer <token> header.

​
Server Logs

Surge maintains timestamped log files for debugging and monitoring:
  • Linux: ~/.local/state/surge/logs/
  • macOS: ~/Library/Application Support/surge/logs/
  • Windows: %APPDATA%\surge\logs\
By default, Surge keeps the 5 most recent log files. You can change this in settings: 
# In TUI, go to Settings → General → Log Retention Count
The server mode is designed to run 24/7. The daemon architecture ensures efficient resource usage even with many downloads.