Skip to main content
Surge supports connecting to remote servers, allowing you to manage downloads on a different machine from your terminal. This is perfect for controlling a home server, NAS, or cloud instance.

​
Connection Methods

There are three ways to connect to a remote Surge server:
Use the surge connect command for a streamlined connection:
surge connect 192.168.1.10:1700 --token <your-token>
This launches the TUI connected to the remote server.

​
Local Server Auto-Detection

When you run surge connect without arguments, it auto-detects the local server: 
surge connect
This scans for a Surge server on localhost and connects automatically.
Local server detection scans ports starting from 1700 up to 100 ports ahead to find your running Surge instance.

​
Protocol Selection

Surge automatically chooses the protocol based on the target:
  • http:// for loopback (127.0.0.1) and private IP targets
  • https:// for public IPs and hostnames

​
Override with Insecure HTTP

Force HTTP for public addresses (useful for development): 
surge connect example.com:1700 --insecure-http --token <token>
Using --insecure-http for public servers sends your token in plaintext. Only use this on trusted networks or for testing.

​
Global Connection Flags

These flags are available on all commands:
FlagDescriptionExample
--host <host:port>Target server for TUI and CLI operations--host 192.168.1.10:1700
--token <token>Bearer token for authentication--token abc123xyz
--verbose, -vEnable verbose logging-v

​
Environment Variables

Set these variables to avoid repeating flags: 
export SURGE_HOST=192.168.1.10:1700
export SURGE_TOKEN=your-secure-token-here
Now all Surge commands will connect to the remote server: 
surge

​
Remote CLI Operations

All CLI commands work with remote servers:
1

List downloads

surge --host 192.168.1.10:1700 --token <token> ls
2

Add download

surge --host 192.168.1.10:1700 --token <token> add https://example.com/file.zip
3

Pause download

surge --host 192.168.1.10:1700 --token <token> pause d4f8a2
4

Resume download

surge --host 192.168.1.10:1700 --token <token> resume d4f8a2
5

Delete download

surge --host 192.168.1.10:1700 --token <token> rm d4f8a2

​
Connection Examples

Connect to a Surge server running on your local network:
# Get the token from the remote server first
ssh [email protected] "surge token"

# Connect from your laptop
surge connect 192.168.1.10:1700 --token <token>

​
Shell Profile Configuration

Add remote connection to your shell profile for permanent access: 
export SURGE_HOST=192.168.1.10:1700
export SURGE_TOKEN=your-token-here

# Optional: Create alias
alias surge-remote='surge --host $SURGE_HOST --token $SURGE_TOKEN'

​
Troubleshooting

1

Check server is running

On the remote machine:
surge server status
2

Verify network access

Test connectivity to the server:
curl http://192.168.1.10:1700/health
Should return {"status":"ok"}.
3

Verify token

Get the current token from the remote server:
ssh [email protected] "surge token"
4

Check firewall rules

Ensure port 1700 is open:
# Linux (ufw)
sudo ufw allow 1700/tcp

# Linux (firewalld)
sudo firewall-cmd --add-port=1700/tcp --permanent
sudo firewall-cmd --reload
Use surge --verbose to see detailed connection logs and debug issues.

​
Security Best Practices

  1. Use HTTPS: Always use HTTPS for public servers
  2. Secure Tokens: Treat tokens like passwords - never commit them to version control
  3. Firewall Rules: Restrict access to port 1700 to trusted IPs only
  4. VPN Access: For remote servers, consider using a VPN instead of exposing the port publicly
  5. Rotate Tokens: Periodically restart the server with a new token
Never expose your Surge server to the public internet without proper authentication and HTTPS. Use a reverse proxy like nginx or Caddy for production deployments.