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:
[[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
type | Also accepted | Carrier |
|---|---|---|
raw | tcp, RAW, TCP | none: the protocol runs directly over TCP (or TLS). Same as no transport |
ws | websocket, WS, WEBSOCKET, v2ray-ws, v2ray_websocket | WebSocket |
http | HTTP, v2ray-http, v2ray_http, v2rayhttp | HTTP/1.1 request with a body that never ends |
httpupgrade | http-upgrade, http_upgrade | HTTP Upgrade, then raw bytes |
grpc | GRPC | gRPC "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
| Key | Default | Value |
|---|---|---|
host | the 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 |
headers | none | extra request headers. A Host header here replaces host |
max-early-data | 0 | bytes of the first payload to send in the handshake. Alias max_early_data |
early-data-header-name | none | header 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
| Key | Default | Value |
|---|---|---|
host | the 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 |
method | PUT | HTTP method, converted to upper case |
headers | none | extra request headers; a Host or User-Agent header here replaces the default |
idle-timeout, ping-timeout | — | accepted, but have no effect |
httpupgrade
| Key | Default | Value |
|---|---|---|
host | the proxy's server (with :port when the port is not 80 or 443) | string or array; the first entry is used |
path | / | request path |
headers | none | extra request headers; Host, Connection and Upgrade here replace the defaults |
The request always carries User-Agent: Mozilla/5.0.
grpc
| Key | Default | Value |
|---|---|---|
service-name | none | the gRPC service name configured on the server. Aliases service_name, serviceName. The request path is /<service-name>/Tun |
authority | the proxy's server (with :port when the port is not 80 or 443) | the HTTP/2 :authority. When empty, host is used |
user-agent | grpc-go/1.76.0 | alias user_agent |
multi-mode | false | true 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:
| Transport | ALPN |
|---|---|
ws, http, httpupgrade | http/1.1 |
grpc | h2 |
raw | none 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
rawandgrpctransports only. Withws,httporhttpupgradethe profile loads, but connections fail. - VLESS Vision (
flow = "xtls-rprx-vision") needsrawand TLS or Reality. With any other transport the profile loads, but connections fail.
Examples
VLESS over gRPC with TLS:
[[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:
[[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
- The proxy works without the CDN but not through it: check that
host(orserver-namefor TLS) is the name the CDN serves, and thatpathorservice-namematches the server. - Every connection fails right after the profile loads: look for an
alpnthat misseshttp/1.1orh2, Reality or Vision combined with a non-raw transport, ormulti-mode = true. - The transport seems to do nothing on Trojan, Shadowsocks or another type: only VMess and VLESS use it.
