VLESS — sing-box

sing-box ships a VLESS implementation that interoperates with Xray's client and server, supports XTLS Vision for the post-handshake fast path, and (on the outbound side) speaks XUDP for UDP-over-TLS multiplexing.

Inbound

type: "vless" inbound:

Field	Type	Default	Allowed values	Description
`users`	`[]VLESSUser`	`[]`	`<VLESSUser array>`	List of accepted users. At least one entry is required for the inbound to accept connections.
`multiplex`	`*InboundMultiplexOptions`	`(disabled)`	`InboundMultiplexOptions`	Server-side multiplex (smux/yamux/h2mux). The block is documented on the Multiplex page in Phase 4.
`transport`	`*V2RayTransportOptions`	`(plain TCP)`	`V2RayTransportOptions`	Optional V2Ray-style transport wrapper: ws, http, grpc, quic, hysteria. See Transport in Phase 4.

Source: option/vless.go:3-9 · pinned at v1.13.11 (553cfa1)

The struct also embeds ListenOptions (listen address, port, sniff, set, …) and InboundTLSOptionsContainer (TLS material). Those blocks are shared by every inbound type and will be documented on the Inbounds and TLS pages in Phase 4.

`users[]`

Field	Type	Default	Allowed values	Description
`name`	`string`	`(unset)`	`<string>`	Display name for the user; used as the stats/logging tag.
`uuid`	`string`	`(required)`	`<UUID>`	User UUID. Required. Canonical 8-4-4-4-12 form.
`flow`	`string`	`(empty)`	`\| xtls-rprx-vision`	Per-user flow algorithm. Empty = plain VLESS; `xtls-rprx-vision` enables Vision.

Source: option/vless.go:11-15 · pinned at v1.13.11 (553cfa1)

Outbound

type: "vless" outbound:

Field	Type	Default	Allowed values	Description
`uuid`	`string`	`(required)`	`<UUID>`	User UUID accepted by the upstream server.
`flow`	`string`	`(empty)`	`\| xtls-rprx-vision`	Flow algorithm; must match what the server expects.
`network`	`NetworkList`	`(tcp+udp)`	`tcp \| udp \| <empty for both>`	Restrict to TCP-only or UDP-only. Empty enables both.
`multiplex`	`*OutboundMultiplexOptions`	`(disabled)`	`OutboundMultiplexOptions`	Client-side multiplex. Must match the server's multiplex configuration.
`transport`	`*V2RayTransportOptions`	`(plain TCP)`	`V2RayTransportOptions`	V2Ray-style transport (ws, http, grpc, etc.).
`packet_encoding`	`*string`	`(unset)`	`packetaddr \| xudp`	Encoding used to carry UDP packets inside the VLESS stream. `xudp` matches Xray's XUDP; `packetaddr` is the older single-stream form.

Source: option/vless.go:17-27 · pinned at v1.13.11 (553cfa1)

The struct embeds DialerOptions (bind interface, routing mark, detour, …), ServerOptions (server, server_port), and OutboundTLSOptionsContainer (tls).

Examples

Inbound with one user and XTLS Vision:

json

{
  "inbounds": [
    {
      "type": "vless",
      "tag": "vless-in",
      "listen": "::",
      "listen_port": 443,
      "users": [
        { "name": "alice", "uuid": "a3482e88-686a-4a58-8126-99c9df64b7bf", "flow": "xtls-rprx-vision" }
      ],
      "tls": {
        "enabled": true,
        "server_name": "example.com",
        "certificate_path": "/etc/ssl/cert.pem",
        "key_path": "/etc/ssl/key.pem"
      }
    }
  ]
}

Outbound via REALITY, sending UDP through XUDP:

json

{
  "outbounds": [
    {
      "type": "vless",
      "tag": "proxy",
      "server": "example.com",
      "server_port": 443,
      "uuid": "a3482e88-686a-4a58-8126-99c9df64b7bf",
      "flow": "xtls-rprx-vision",
      "packet_encoding": "xudp",
      "tls": {
        "enabled": true,
        "server_name": "www.google.com",
        "utls": { "enabled": true, "fingerprint": "chrome" },
        "reality": { "enabled": true, "public_key": "...", "short_id": "..." }
      }
    }
  ]
}

Notes

A VLESS server in sing-box uses users[].uuid, not clients[].id like Xray. The same UUID works on either implementation; only the JSON key changes.
sing-box does not support Xray's fallbacks mechanism inside VLESS; the equivalent behavior is provided by the fallback field on the shared tls block (which forwards on TLS-handshake mismatch).
The packet_encoding choices come from proxy/vless/packetaddr upstream. xudp is the modern default and matches the encoding Xray uses when its flow field includes the -udp443 suffix.
users[].flow and the implicit "no flow" combine: a server with no Vision users still accepts plain-VLESS clients on the same port.

Cross-core notes

Xray uses clients[].id (UUID) and accepts a fallbacks array on the inbound. See VLESS — Xray-core.
mihomo packs everything into a single proxy object (no separate users array on the outbound). See VLESS — mihomo.

Source: option/vless.go:3-27 · v1.13.11 (553cfa1)

VLESS — sing-box ​

Inbound ​

users[] ​

Outbound ​

Examples ​

Notes ​

Cross-core notes ​