VMess
Surge supports the VMess protocol, the proxy protocol of the V2Ray project, including the AEAD handshake, optional TLS, and WebSocket transport.
[Proxy]
Proxy-VMess = vmess, 1.2.3.4, 8000, username=0233d11c-15a4-47d3-ade3-48ffca0ce119
Declaration syntax:
Name = vmess, <host>, <port>, username=<UUID>[, parameter=value, ...]
VMess supports UDP relay. No parameter is required; UDP forwarding is available automatically.
Parameters
username
Required.
The VMess user ID. It must be a valid UUID.
encrypt-method
Optional, aes-128-gcm or chacha20-ietf-poly1305, default: aes-128-gcm.
The data encryption method.
vmess-aead
Optional, Boolean, default: false.
Use the VMess AEAD handshake instead of the legacy handshake. It must match the server's setting.
tls
Optional, Boolean, default: false.
Connect to the server over TLS. When enabled, the TLS parameters also apply.
ws
Optional, Boolean, default: false.
Use the WebSocket transport layer.
ws-path
Optional, default: /.
The path used for the WebSocket handshake. It must start with /.
ws-headers
Optional.
Extra headers for the WebSocket handshake, as pipe-separated Header:Value pairs:
Proxy-VMess = vmess, 1.2.3.4, 8000, username=0233d11c-15a4-47d3-ade3-48ffca0ce119, ws=true, ws-path=/v2, ws-headers=Host:example.com|X-Token:abc
ws-http-upgrade iOS 6.0.0+ Mac 6.12.0+
Optional, Boolean, default: false. Requires ws=true.
Use the HTTPUpgrade transport (network: httpupgrade in Xray and sing-box) instead of WebSocket. The client sends the same WebSocket upgrade request with ws-path and ws-headers, and after the server's 101 Switching Protocols the data flows without WebSocket framing, which costs less than WebSocket and passes through CDNs and reverse proxies the same way.
- The
Hostheader is the one inws-headers, then thesni, then the server address. Without aUser-Agentinws-headers, Surge sends Chrome's headers as Xray does. - An
edquery parameter inws-path(Xray's early-data setting) is removed from the request. Surge always waits for the server's response before sending data. - Unlike WebSocket, a half-closed connection is passed through.
Proxy-VMess-HTTPUpgrade = vmess, 1.2.3.4, 443, username=0233d11c-15a4-47d3-ade3-48ffca0ce119, tls=true, ws=true, ws-http-upgrade=true, ws-path=/up, ws-headers=Host:example.com
Common Parameters
All proxy policies accept the common policy parameters, such as interface, tfo, test-url, and underlying-proxy. With tls=true, the TLS parameters apply, such as sni, skip-cert-verify, and client-cert. For details on UDP forwarding behavior, see UDP Relay.