HTTP, HTTPS, and HTTP/2 CONNECT Proxy

Surge supports the standard HTTP proxy family: plain HTTP proxy (http), HTTP proxy over TLS (https), and HTTP/2 CONNECT proxy (h2-connect). Use these types when connecting to a standard proxy server such as Squid, TinyProxy, or another Surge-compatible HTTP proxy endpoint.

[Proxy]
ProxyHTTP = http, 1.2.3.4, 443, username, password
ProxyHTTPS = https, 1.2.3.4, 443, username, password
ProxyH2 = h2-connect, example.com, 443

Declaration syntax:

Name = http, <host>, <port>[, <username>, <password>][, parameter=value, ...]
Name = https, <host>, <port>[, <username>, <password>][, parameter=value, ...]
Name = h2-connect, <host>, <port>[, parameter=value, ...]

The https and h2-connect Mac 6.6.0+ types always connect over TLS. HTTP/2 CONNECT multiplexes multiple requests over a single TCP connection.

None of these types supports UDP relay.

Parameters

username / password

Optional.

Credentials for proxy authentication. They may be given positionally after the port, or as named parameters:

ProxyH2 = h2-connect, example.com, 443, username=user, password=pass

always-use-connect

Optional, Boolean, default: false.

Always use the HTTP CONNECT method to relay the request, even for plain HTTP requests. Applies to http and https only.

headers Mac 6.6.0+

Optional.

Add custom request headers to proxy handshake requests. Multiple headers are separated by semicolons.

Proxy = http, example.com, 8080, headers=X-Client:Surge;X-Token:abc
Proxy = h2-connect, example.com, 443, headers=X-Padding:<random-string(16-32)>

The value supports <random-string(n)> and <random-string(min-max)> placeholders. Surge generates a URL-safe random string when connecting, which can be used for dynamic padding or request fingerprint perturbation.

For HTTP and HTTPS proxy policies, a configured header replaces an original field with the same name, including the Host field. iOS 5.20.0+ Mac 6.7.0+

max-streams Mac 6.6.0+

Optional, default: 3.

For h2-connect only. Control the maximum number of multiplexed sub-connections over the same TCP connection. A large value may hurt performance in some environments.

Common Parameters

All proxy policies accept the common policy parameters, such as interface, tfo, test-url, and underlying-proxy. Since https and h2-connect connect over TLS, they also accept the TLS parameters, such as sni, skip-cert-verify, and client-cert.