Skip to main content
The connect command launches the Terminal User Interface (TUI) connected to a running Surge server, either local or remote.

​
Usage

surge connect [host:port]

​
Description

Connects the Surge TUI to a running server daemon. The command:
  • Auto-detects locally running servers when no target is specified
  • Connects to remote servers via HTTP/HTTPS API
  • Provides full TUI functionality for remote download management
  • Supports secure HTTPS connections for remote hosts
  • Validates connection and authentication before starting TUI
This command is a convenience wrapper for remote TUI mode. It’s equivalent to running surge --host <host:port>.

​
Arguments

​
host:port
string
Target server address in host:port format. If omitted, auto-detects a locally running server.Examples:
surge connect 192.168.1.100:1700
surge connect localhost:8080
Can also use full URLs:
surge connect http://localhost:1700
surge connect https://remote-server.com:1700

​
Flags

​
--insecure-http
boolean
default:"false"
Allow plain HTTP connections for non-loopback targets. By default, remote servers require HTTPS for security.Example:
surge connect 192.168.1.100:1700 --insecure-http
Only use --insecure-http on trusted local networks. HTTPS is strongly recommended for remote connections.

​
Examples

​
Auto-Detect Local Server

Start server: 
surge server
In another terminal: 
surge connect
Output: 
Auto-detected local server on port 1700
Connecting to http://127.0.0.1:1700...
The TUI will launch connected to the local server.

​
Connect to Localhost

surge connect localhost:1700
Or: 
surge connect 127.0.0.1:1700

​
Connect to Remote Server

Using HTTPS (recommended): 
surge connect https://remote-server.com:1700 --token <token>
Using HTTP on local network: 
surge connect 192.168.1.100:1700 --insecure-http --token <token>

​
With Environment Variables

Set once: 
export SURGE_HOST=192.168.1.100:1700
export SURGE_TOKEN=your-token-here
Then connect: 
surge connect

​
Connection Modes

​
Local Auto-Detection

When no target is specified, surge connect reads the port from: 
~/.local/state/surge/port
This file is created by surge and surge server commands.

​
HTTP vs HTTPS

Target TypeDefault SchemeOverride
localhost / 127.0.0.1HTTPUse full URL
Private IP (192.168.x.x, 10.x.x.x)HTTPUse full URL
Remote hostname/IPHTTPSUse --insecure-http
Full URL providedUse scheme from URLN/A
Examples: 
# Auto HTTP (loopback)
surge connect localhost:1700

# Auto HTTP (private IP)
surge connect 192.168.1.100:1700 --insecure-http

# Force HTTPS
surge connect https://192.168.1.100:1700

# Force HTTP for remote
surge connect http://example.com:1700 --insecure-http

​
Authentication

​
Token Resolution

Tokens are resolved in this order:
  1. --token flag
  2. SURGE_TOKEN environment variable
  3. Local token file (for localhost/same machine only)

​
Local Servers

For localhost connections, the token is automatically read from: 
~/.local/state/surge/token
No need to specify --token: 
surge connect localhost:1700

​
Remote Servers

Remote connections require explicit authentication: 
# Using flag
surge connect 192.168.1.100:1700 --token abc123...

# Using environment variable
export SURGE_TOKEN=abc123...
surge connect 192.168.1.100:1700
Get the token from the remote server: 
ssh [email protected] "surge token"

​
TUI Features

When connected, the TUI provides:
  • Real-time download progress
  • Add/remove downloads
  • Pause/resume controls
  • Live event stream from server
  • Full keyboard navigation
  • Settings management (reads from remote server)
The TUI operates in remote mode - all actions are sent to the server via HTTP API.

​
Error Handling

​
No Local Server

No local Surge server detected. Start one with 'surge' or 'surge server', or specify a target: surge connect <host:port>
Solution: 
# Start a server first
surge server

# Or connect to remote
surge connect 192.168.1.100:1700

​
Connection Failed

Failed to connect: connection refused
Check that the server is running: 
surge server status

​
Authentication Failed

Failed to connect: 401 Unauthorized
Verify the token: 
# On server machine
surge token

# Use correct token
surge connect 192.168.1.100:1700 --token <correct-token>

​
HTTPS Required

Error: refusing insecure HTTP for non-loopback target. Use https:// or --insecure-http
Options: 
# Use HTTPS
surge connect https://remote-server.com:1700

# Or allow HTTP (not recommended for internet)
surge connect 192.168.1.100:1700 --insecure-http

​
Use Cases

​
Monitor Remote Downloads

Connect to a headless server to monitor downloads: 
surge connect 192.168.1.100:1700

​
Multiple Terminals

Run server in one terminal: 
surge server
Connect TUI in another: 
surge connect
Add downloads from a third: 
surge add https://example.com/file.zip

​
SSH Port Forwarding

Securely connect to remote server: 
# On local machine
ssh -L 1700:localhost:1700 user@remote-server

# In another terminal
surge connect localhost:1700

​
Container/Docker

Connect to Surge running in a container: 
# Container exposes port 1700
docker run -d -p 1700:1700 surge-image surge server

# Connect from host
surge connect localhost:1700

​
Network Configuration

​
Firewall Rules

For remote connections, open the port: 
sudo ufw allow 1700/tcp

​
Reverse Proxy

For HTTPS support, use nginx or caddy: Nginx: 
server {
    listen 443 ssl;
    server_name surge.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:1700;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}
Then connect: 
surge connect https://surge.example.com --token <token>

​
Comparison with —host Flag

These are equivalent: 
surge connect 192.168.1.100:1700
surge --host 192.168.1.100:1700
surge connect is a dedicated command for clarity, while --host can be used with the main surge command.