Protocols

xrat supports 7 proxy protocols, each with specific URI formats, configuration fields, and engine routing.

Supported Protocols

VLESS

Modern, lightweight protocol from the Xray project.

Scheme: vless://

Format:

vless://<uuid>@<address>:<port>?type=<network>&security=<tls>&sni=<sni>&host=<host>&path=<path>#<name>

Fields:

REALITY: when security=reality, xrat builds current Xray realitySettings from pbk/password, sid, spx, fp, and sni. The share-link public key is emitted as Xray’s current password field and is required. REALITY is accepted only with raw, xhttp, or gRPC transports.

All non-structural query parameters are preserved. xrat generates current raw, WebSocket, gRPC, xhttp, mKCP, and HTTPUpgrade settings when representable and fails with a named unsupported-parameter/transport error instead of silently dropping a wire-affecting value.

For xhttp, current flat parameters use Xray’s camelCase names, including xPaddingBytes, xPaddingObfsMode, noGRPCHeader, noSSEHeader, headers, xmux, and downloadSettings. The compatibility aliases x_padding_bytes and the URL-encoded x_padding%20bytes are also accepted for xPaddingBytes.

Newer Xray xhttp options can be passed in the URL-encoded extra query parameter as a JSON object. Fields inside extra are preserved so links can use options introduced by newer Xray versions. A canonical flat parameter overrides the same field in extra; extra overrides compatibility aliases. Unknown flat parameters, malformed values, repeated singular parameters, and conflicting aliases are rejected. Whether a future field works at runtime still depends on the installed Xray version.

Examples:

vless://uuid-123@example.com:443?type=ws&security=tls&sni=cdn.example.com&path=%2Fray#My%20Node
vless://uuid-456@example.com:443?type=tcp#Direct
vless://uuid-789@example.com:8443?type=grpc&serviceName=service#gRPC%20Node
vless://uuid-abc@example.com:8080?type=xhttp&security=reality&sni=www.example.com&pbk=PUBLICKEY&sid=SHORTID&fp=chrome&flow=xtls-rprx-vision#REALITY%20Node
vless://uuid-def@example.com:443?type=xhttp&mode=auto&xPaddingBytes=100-1000&extra=%7B%22noSSEHeader%22%3Atrue%7D#XHTTP%20Node

Engine: Xray (auto), Xray or sing-box (explicit)

VMess

Legacy protocol with encryption, from V2Ray.

Scheme: vmess://

Current AEAD URL format:

vmess://<uuid>@<address>:<port>?type=<network>&security=<tls>&encryption=<cipher>&sni=<sni>&host=<host>&path=<path>#<name>

The URL form uses the same normalized transport, TLS, REALITY, and fm fields as VLESS. Its UUID, host, and port are required, and duplicate query keys are rejected. encryption defaults to auto when omitted.

Legacy format (still supported):

vmess://<base64-json>

Base64 JSON Fields:

{
  "add": "example.com",
  "port": "443",
  "id": "uuid-456",
  "net": "ws",
  "tls": "tls",
  "sni": "edge.example.com",
  "host": "host.example.com",
  "path": "/vmess",
  "ps": "VMess Node"
}

Example:

vmess://00000000-0000-0000-0000-000000000001@example.com:443?type=ws&security=tls&encryption=auto&host=cdn.example.com&path=%2Fvmess#VMess%20AEAD
vmess://eyJhZGQiOiJleGFtcGxlLmNvbSIsInBvcnQiOiI0NDMiLCJpZCI6InV1aWQtNDU2IiwibmV0Ijoid3MiLCJ0bHMiOiJ0bHMiLCJzbmkiOiJlZGdlLmV4YW1wbGUuY29tIiwiaG9zdCI6Imhvc3QuZXhhbXBsZS5jb20iLCJwYXRoIjoiL3ZtZXNzIiwicHMiOiJWTWVzcyBOb2RlIn0=

Engine: Xray (auto), Xray or sing-box (explicit)

Shadowsocks

Simple, secure proxy protocol.

Scheme: ss://

Format:

ss://<base64(method:password)>@<address>:<port>#<name>

Fields:

Encryption methods: aes-128-gcm, aes-256-gcm, chacha20-ietf-poly1305, xchacha20-ietf-poly1305, aes-128-cfb, aes-256-cfb, rc4-md5

Example:

ss://YWVzLTI1Ni1nY206c2VjcmV0@example.com:8388#SS%20Node

Engine: Xray (auto), Xray or sing-box (explicit)

Trojan

TLS-based proxy that mimics HTTPS traffic.

Scheme: trojan://

Format:

trojan://<password>@<address>:<port>?type=<network>&sni=<sni>&host=<host>&path=<path>#<name>

Fields:

Default TLS: Trojan always uses TLS (security=tls is added automatically).

Examples:

trojan://password@example.com:443?type=ws&sni=cdn.example.com&path=%2Ftrojan#Trojan%20Node

Engine: Xray (auto), Xray or sing-box (explicit)

HTTP

Standard HTTP/HTTPS proxy.

Scheme: http:// / https://

Format:

http://<username>:<password>@<address>:<port>#<name>
https://<username>:<password>@<address>:<port>#<name>

Fields:

TLS: https:// scheme automatically sets tls=tls.

Examples:

http://user:pass@example.com:8080#HTTP%20Node
https://example.com:443#HTTPS%20Node

Engine: Xray (auto), Xray or sing-box (explicit)

SOCKS5

Standard SOCKS5 proxy.

Scheme: socks5://

Format:

socks5://<username>:<password>@<address>:<port>#<name>

Fields:

Examples:

socks5://user:pass@example.com:1080#SOCKS%20Node
socks5://example.com:1080#Anonymous

Engine: Xray (auto), Xray or sing-box (explicit)

Hysteria2

QUIC-based protocol designed for high-speed connections.

Scheme: hysteria2:// / hy2://

Format:

hysteria2://<password>@<address>:<port>?sni=<sni>&obfs=<type>&obfs-password=<pass>#<name>
hy2://<password>@<address>:<port>?sni=<sni>&obfs=<type>&obfs-password=<pass>#<name>

Fields:

Default network: udp (not configurable) Default TLS: tls (always enabled)

Examples:

hy2://password@example.com:443?sni=cdn.example.com&obfs=salamander&obfs-password=secret#HY2%20Node
hy2://password@example.com:8443#Simple%20HY2
hysteria2://password@example.com:443#Alias

Engine: sing-box (xrat parse --engine auto), Xray (--engine xray), or sing-box (--engine sing-box). The managed runtime follows [runtime].engine: Xray and sing-box support Hysteria2; V2Ray does not. Xray generation rejects URI options that have no supported native mapping, including obfuscation and bandwidth parameters.

Engine Routing

Engine selection is automatic but configurable.

Auto Mode (Default)

Xray Mode

All listed protocols, including Hysteria2 when its URI fields can be represented by Xray.

sing-box Mode

All protocols use sing-box generation. Each outbound maps to documented sing-box 1.13 fields; unsupported link parameters and transports fail with a named error before launch instead of being dropped. The managed runtime and xrat test both require a sing-box >=1.13.0 binary; newer versions are accepted with a warning outside the planned >=1.13.0, <1.15.0 conformance range, and the target is v1.13.21.

Checking Engine

xrat parse --engine auto "vless://uuid@example.com:443"
xrat parse --engine sing-box "hy2://password@example.com:443"

Engine and Stage Support

Every protocol xrat imports can be parsed, shown, probed, and run through a managed Xray, V2Ray (except Hysteria2), or sing-box runtime. xrat test probes with the binary selected by [runtime].engine; the sing-box probe path generates a sing-box probe config and spawns sing-box run -c.

Managed sing-box sessions and sing-box probes require a sing-box >=1.13.0 binary. Newer versions are accepted; the planned conformance range is >=1.13.0, <1.15.0 with v1.13.21 pinned, and versions outside it log a warning. A pre-1.13 or unavailable binary is rejected before a config is written or a process starts.

sing-box Limitations and Expected Errors

geosite/geoip categories map to remote SagerNet rule-sets (sing-geosite/sing-geoip) referenced from the generated route. Remote rule-sets are downloaded on first use and cached under the runtime directory via experimental.cache_file; they require network access and cannot reuse Xray’s local .dat assets.

Normalized Fields

All protocols are normalized to a common Node structure: