VLESS iOS 6.0.0+ Mac 6.12.0+

VLESS is the lightweight proxy protocol of the Xray project. Surge implements the client side as Xray-core does, including REALITY and the XTLS Vision flow.

[Proxy]
# RAW + REALITY + Vision, the most common deployment
Proxy-REALITY = vless, 1.2.3.4, 443, username=2cae91b3-f85c-433b-88ee-a002b9ed6d61, flow=xtls-rprx-vision, sni=www.microsoft.com, reality-public-key=dwrjY6KiAMPxKdlF7T4AWFXXBtsxeHCXtBQYeCOdZV4, reality-short-id=0123456789abcdef

# WebSocket + TLS, e.g. behind a CDN
Proxy-WS = vless, example.com, 443, username=2cae91b3-f85c-433b-88ee-a002b9ed6d61, ws=true, ws-path=/vless, tls=true

# RAW + TLS + Vision
Proxy-TLS = vless, example.com, 443, username=2cae91b3-f85c-433b-88ee-a002b9ed6d61, flow=xtls-rprx-vision, tls=true

# gRPC + TLS
Proxy-gRPC = vless, example.com, 443, username=2cae91b3-f85c-433b-88ee-a002b9ed6d61, grpc=true, grpc-service-name=mygrpc, tls=true

Declaration syntax:

Name = vless, <host>, <port>, username=<user ID>[, parameter=value, ...]

Supported combinations:

XHTTP, HTTPUpgrade and mKCP transports and VLESS Encryption are not supported.

Parameters

username

Required.

The VLESS user ID (id in Xray). It is usually a UUID. Like Xray, Surge also accepts any other string of 1 to 30 bytes and maps it to a UUIDv5, so username=my-user matches a server whose client id is my-user.

flow

Optional, xtls-rprx-vision or xtls-rprx-vision-udp443.

Enables the XTLS Vision flow. It must match the server's setting for the user. Vision requires TLS 1.3 to the server, through tls=true or REALITY, and cannot be used with WebSocket. Both values behave the same in Surge; use block-quic to control QUIC traffic.

reality-public-key

Optional.

The REALITY public key of the server (password or publicKey in Xray client configs, pbk in share links), as printed by xray x25519. Base64 with or without padding and URL-safe Base64 are accepted. Setting it enables REALITY, which implies TLS.

With REALITY, sni must be one of the serverNames configured on the server. The server's certificate is verified by the REALITY handshake instead of the system trust store, so skip-cert-verify and certificate pinning do not apply. Session resumption is disabled for REALITY connections.

reality-short-id

Optional, default: empty.

The REALITY short ID (shortId / sid), up to 16 hexadecimal digits. It must be one of the server's shortIds. Requires reality-public-key.

encryption

Optional, only none is accepted.

Present for compatibility with share links. VLESS Encryption (mlkem768x25519plus...) is not supported.

tls

Optional, Boolean, default: false.

Connect to the server over TLS. When enabled, the TLS parameters also apply. Not needed with REALITY.

ws

Optional, Boolean, default: false.

Use the WebSocket transport layer. See VMess for ws-path and ws-headers, which work the same way.

grpc

Optional, Boolean, default: false.

Use the gRPC transport ("gun" in Xray). It requires tls=true or REALITY. All connections of the policy are carried as streams of one HTTP/2 connection to the server.

grpc-service-name

Optional, default: empty.

The gRPC service name (serviceName), which must match the server. As in Xray, a plain name such as mygrpc is sent as the path /mygrpc/Tun, and a name starting with / is a custom path whose last segment names the stream method, for example /my/path/tun|tunmulti.

grpc-mode

Optional, gun or multi, default: gun.

multi uses the TunMulti method (Xray's multiMode). Servers accept both.

grpc-authority

Optional.

The :authority of the gRPC requests. Defaults to sni, or to the server hostname.

UDP Relay

VLESS supports UDP relay with no extra parameter. Surge sends UDP as XUDP, the default of Xray, sing-box and mihomo clients and the only form an Xray server accepts together with the Vision flow. One VLESS connection carries datagrams to any destination, which gives full-cone NAT behavior when the server supports it.

Share Link Parameters

vless://<id>@<host>:<port>?<query>#<name> links map to Surge parameters as follows:

See Also

• Common Policy Parameters — shared parameters such as interface, tfo, test-url, and underlying-proxy.
• TLS Parameters — shared TLS parameters such as skip-cert-verify, sni, alpn, and certificate pinning.
• UDP Relay