Skip to content

Transports ​

A transport wraps a VMess or VLESS connection in another carrier, usually so that it can pass a CDN or a reverse proxy that only forwards web traffic. It is a transport inline table on the proxy:

toml
[[proxy]]
name = "vmess-ws"
type = "vmess"
server = "proxy.example.org"
port = 443
uuid = "e6e1acfe-5b1e-4b1c-87c8-92beecb98ba2"
tls = { server-name = "proxy.example.org" }
transport = { type = "ws", host = "proxy.example.org", path = "/ws" }

The client and the server must use the same transport, path and service name.

Which proxies use it ​

Only vmess and vless use transport. Every other type ignores it without a warning. The table is still checked on every type, though: a transport without type, or with an unknown type, rejects the profile even on a Trojan or Shadowsocks proxy.

Types ​

typeAlso acceptedCarrier
rawtcp, RAW, TCPnone: the protocol runs directly over TCP (or TLS). Same as no transport
wswebsocket, WS, WEBSOCKET, v2ray-ws, v2ray_websocketWebSocket
httpHTTP, v2ray-http, v2ray_http, v2rayhttpHTTP/1.1 request with a body that never ends
httpupgradehttp-upgrade, http_upgradeHTTP Upgrade, then raw bytes
grpcGRPCgRPC "gun" stream over HTTP/2

There is no h2, quic, xhttp or splithttp transport.

Keys ​

path always starts with /: Specola adds a missing leading slash, and an empty path becomes /. headers is an inline table of string values. Keys are lenient: an unknown key is ignored without a warning.

ws ​

KeyDefaultValue
hostthe proxy's server (with :port when the port is not 80 or 443)string or array; with an array, one is picked at random for each connection. Write it without a port
path/request path
headersnoneextra request headers. A Host header here replaces host
max-early-data0bytes of the first payload to send in the handshake. Alias max_early_data
early-data-header-namenoneheader that carries the early data, base64-encoded; for example Sec-WebSocket-Protocol. Alias early_data_header_name

Early data is sent only when both max-early-data and early-data-header-name are set. Early data through the path (/ws?ed=2048) is not supported: the path is sent as written.

http ​

KeyDefaultValue
hostthe proxy's server (with :port when the port is not 80 or 443)string or array; one is picked at random for each connection
path/request path
methodPUTHTTP method, converted to upper case
headersnoneextra request headers; a Host or User-Agent header here replaces the default
idle-timeout, ping-timeout—accepted, but have no effect

httpupgrade ​

KeyDefaultValue
hostthe proxy's server (with :port when the port is not 80 or 443)string or array; the first entry is used
path/request path
headersnoneextra request headers; Host, Connection and Upgrade here replace the defaults

The request always carries User-Agent: Mozilla/5.0.

grpc ​

KeyDefaultValue
service-namenonethe gRPC service name configured on the server. Aliases service_name, serviceName. The request path is /<service-name>/Tun
authoritythe proxy's server (with :port when the port is not 80 or 443)the HTTP/2 :authority. When empty, host is used
user-agentgrpc-go/1.76.0alias user_agent
multi-modefalsetrue is accepted when the profile loads, but every connection fails: multi-mode is not supported

Always set service-name; without it the path is //Tun, which servers rarely expect.

ALPN ​

When TLS is on, a transport needs a specific ALPN protocol:

TransportALPN
ws, http, httpupgradehttp/1.1
grpch2
rawnone required

Without alpn in the tls table, Specola offers the right one. If you set alpn, it must contain that protocol: alpn = ["h2"] with ws, for example, loads but every connection fails with configured ALPN is incompatible with the selected transport.

Reality and Vision ​

  • Reality works with the raw and grpc transports only. With ws, http or httpupgrade the profile loads, but connections fail.
  • VLESS Vision (flow = "xtls-rprx-vision") needs raw and TLS or Reality. With any other transport the profile loads, but connections fail.

Examples ​

VLESS over gRPC with TLS:

toml
[[proxy]]
name = "vless-grpc"
type = "vless"
server = "proxy.example.org"
port = 443
uuid = "63478227-37be-44ee-a7e3-a2cfa1108664"
tls = { server-name = "proxy.example.org" }
transport = { type = "grpc", service-name = "example-service" }

VMess over HTTP Upgrade behind a CDN, with an extra header:

toml
[[proxy]]
name = "vmess-upgrade"
type = "vmess"
server = "cdn.example.org"
port = 443
uuid = "e6e1acfe-5b1e-4b1c-87c8-92beecb98ba2"
tls = { server-name = "proxy.example.org" }
transport = { type = "httpupgrade", host = "proxy.example.org", path = "/upgrade", headers = { X-Client = "specola" } }

Troubleshooting ​

  1. The proxy works without the CDN but not through it: check that host (or server-name for TLS) is the name the CDN serves, and that path or service-name matches the server.
  2. Every connection fails right after the profile loads: look for an alpn that misses http/1.1 or h2, Reality or Vision combined with a non-raw transport, or multi-mode = true.
  3. The transport seems to do nothing on Trojan, Shadowsocks or another type: only VMess and VLESS use it.

See also Proxies and TLS.