VMess — sing-box

sing-box implements both VMess sides. It still accepts the legacy alter_id-based MD5-AEAD mode (useful for compatibility with older clients) and adds two newer toggles — global_padding and authenticated_length — that have to match between client and server.

Inbound

type: "vmess" inbound:

Field	Type	Default	Allowed values	Description
`users`	`[]VMessUser`	`[]`	`<VMessUser array>`	List of accepted users.
`multiplex`	`*InboundMultiplexOptions`	`(disabled)`	`InboundMultiplexOptions`	Server-side multiplex (smux/yamux/h2mux).
`transport`	`*V2RayTransportOptions`	`(plain TCP)`	`V2RayTransportOptions`	Optional V2Ray-style transport wrapper (ws, http, grpc, quic, hysteria).

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

The struct embeds ListenOptions (listen address, port, sniff, …) and InboundTLSOptionsContainer (TLS material). Both are shared across every inbound and ship with the Inbounds and TLS pages in Phase 4.

`users[]`

Field	Type	Default	Allowed values	Description
`name`	`string`	`(unset)`	`<string>`	Display name used in stats and logs.
`uuid`	`string`	`(required)`	`<UUID>`	User UUID.
`alterId`	`int`	`0`	`0 \| <int>`	Legacy MD5-AEAD compatibility. Keep at 0 for the modern AEAD-only mode; a non-zero value opts into the deprecated MD5 stream cipher and is rejected by some peers.

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

Outbound

type: "vmess" outbound:

Field	Type	Default	Allowed values	Description
`uuid`	`string`	`(required)`	`<UUID>`	User UUID accepted by the upstream server.
`security`	`string`	`auto`	`auto \| none \| zero \| aes-128-gcm \| chacha20-poly1305 \| aes-128-ctr`	Symmetric cipher. `auto` picks AES-GCM on x86 with AES-NI and ChaCha20 elsewhere.
`alter_id`	`int`	`0`	`0 \| <int>`	Legacy MD5-AEAD mode. Snake-cased here (Xray uses `alterId`).
`global_padding`	`bool`	`false`	`true \| false`	Pad all writes to a uniform length to hinder length-based fingerprinting. Must match the server side.
`authenticated_length`	`bool`	`false`	`true \| false`	Use the experimental authenticated-length framing. Must match the server side.
`network`	`NetworkList`	`(tcp+udp)`	`tcp \| udp \|`	Restrict to TCP-only or UDP-only. Empty enables both.
`packet_encoding`	`string`	`(unset)`	`packetaddr \| xudp`	Encoding for UDP packets carried through the VMess stream.
`multiplex`	`*OutboundMultiplexOptions`	`(disabled)`	`OutboundMultiplexOptions`	Client-side multiplex (must match the server).
`transport`	`*V2RayTransportOptions`	`(plain TCP)`	`V2RayTransportOptions`	V2Ray-style transport wrapper.

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

Also embeds DialerOptions, ServerOptions (server, server_port), and OutboundTLSOptionsContainer (tls).

Examples

Inbound:

json

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

Outbound over WebSocket with TLS:

json

{
  "outbounds": [
    {
      "type": "vmess",
      "tag": "proxy",
      "server": "example.com",
      "server_port": 443,
      "uuid": "a3482e88-686a-4a58-8126-99c9df64b7bf",
      "security": "auto",
      "alter_id": 0,
      "global_padding": true,
      "authenticated_length": true,
      "packet_encoding": "xudp",
      "tls": { "enabled": true, "server_name": "example.com" },
      "transport": { "type": "ws", "path": "/vm" }
    }
  ]
}

Notes

The inbound user key is alterId (camelCase) but the outbound option is alter_id (snake_case) — a quirk of the upstream config history. Both default to 0 and both opt into the legacy MD5 mode when set non-zero.
global_padding and authenticated_length are sing-box additions over the original V2Ray spec. Both sides must enable them; mixing them produces silent connection failure.
Unlike Xray, sing-box does not print a deprecation warning when VMess is loaded — it treats the protocol as stable.

Cross-core notes

Xray drops the AEAD-less legacy mode entirely; there is no alterId field, and the runtime prints a deprecation banner steering users toward VLESS. See VMess — Xray-core.
mihomo uses the field name cipher (where Xray and sing-box use security), keeps alterId (camelCase), and surfaces the same global-padding / authenticated-length toggles in kebab-case. See VMess — mihomo.

Source: option/vmess.go:3-30 · v1.13.11 (553cfa1)

VMess — sing-box ​

Inbound ​

users[] ​

Outbound ​

Examples ​

Notes ​

Cross-core notes ​