VMess — Xray-core

VMess is the classic AEAD-only V2Ray protocol. Xray-core supports only the AEAD variant — the alterId-based MD5-AEAD mode is not supported. The runtime emits a deprecation notice on startup that recommends VLESS encryption (infra/conf/vmess.go:65, 124).

Inbound

settings for an inbound of "protocol": "vmess":

Field	Type	Default	Allowed values	Description
users	[]json.RawMessage	—	<user object array> | …	Inbound account list; same object shape as clients. Either key is accepted.
clients	[]json.RawMessage	(required)	<user object array>	List of accepted users. Each entry holds the VMess account fields (id, security, experiments) plus the common user fields (email, level).
default	*VMessDefaultConfig	(unset)	VMessDefaultConfig	Fallback user settings when an incoming connection does not match a configured client. Only the level field exists today.

Source: infra/conf/vmess.go:57-61 · pinned at v26.9.9 (52a412d)

default

Field	Type	Default	Allowed values	Description
level	byte	0	<byte>	Policy level applied to fallback users.

Source: infra/conf/vmess.go:46-48 · pinned at v26.9.9 (52a412d)

clients[] — user object

Each clients[] entry is a VMessAccount plus the common user fields (email, level):

Field	Type	Default	Allowed values	Description
id	string	(required)	<UUID>	User UUID. Canonical 8-4-4-4-12 or dash-less hex. Parsed and re-canonicalized on load.
security	string	auto	auto | aes-128-gcm | chacha20-poly1305	Symmetric cipher for the VMess payload. auto picks AES-GCM on x86 with AES-NI and ChaCha20 elsewhere. Unrecognized values silently fall back to auto.
experiments	string	(unset)	<string>	Comma-separated experiment flags forwarded into the protocol. Forwarded as TestsEnabled in the protobuf.

Source: infra/conf/vmess.go:18-22 · pinned at v26.9.9 (52a412d)

Outbound

settings for an outbound of "protocol": "vmess":

Field	Type	Default	Allowed values	Description
address	*Address	(unset)	<host>	Simplified shape — server hostname or IP. When set, vnext is constructed internally.
port	uint16	(required with address)	<port>	Server port (simplified shape).
level	uint32	0	<uint32>	User level (simplified shape).
email	string	(unset)	<string>	User identifier reported in stats.
id	string	(required with address)	<UUID>	User UUID (simplified shape).
security	string	auto	auto | aes-128-gcm | chacha20-poly1305	Same cipher set as inbound clients.
experiments	string	(unset)	<string>	Experiment flags forwarded to the server.
vnext	[]*VMessOutboundTarget	(use simplified shape)	[{address,port,users:[user]}]	Verbose shape — must hold exactly one server with exactly one user.

Source: infra/conf/vmess.go:111-120 · pinned at v26.9.9 (52a412d)

Simplified vs. vnext

The outbound accepts either the simplified shape (address, port, id, security, ...) or the verbose vnext shape. The simplified form is rewritten into a single-entry vnext array (infra/conf/vmess.go:127-135). The verbose form must hold exactly one server with exactly one user — for multiple endpoints use multiple VMess outbounds and a routing balancer.

Examples

Minimal inbound:

{
  "inbounds": [
    {
      "tag": "vmess-in",
      "listen": "0.0.0.0",
      "port": 443,
      "protocol": "vmess",
      "settings": {
        "clients": [
          { "id": "a3482e88-686a-4a58-8126-99c9df64b7bf", "email": "alice", "security": "auto" }
        ]
      },
      "streamSettings": { "network": "tcp", "security": "tls" }
    }
  ]
}

Simplified outbound:

{
  "outbounds": [
    {
      "tag": "vmess-out",
      "protocol": "vmess",
      "settings": {
        "address": "example.com",
        "port": 443,
        "id": "a3482e88-686a-4a58-8126-99c9df64b7bf",
        "security": "auto"
      },
      "streamSettings": { "network": "ws", "security": "tls", "wsSettings": { "path": "/vm" } }
    }
  ]
}

Notes

• VMess in Xray is AEAD-only. There is no alterId field in the config struct; drop "alterId": <n> from configs written for V2Ray — the MD5-AEAD mode is rejected either way.
• security: "auto" is the safe default: AES-GCM on platforms with AES-NI, ChaCha20-Poly1305 otherwise. Unknown security strings silently fall back to auto (infra/conf/vmess.go:34-35).
• none and zero are not recognized security values — configs carrying them silently get auto.
• A startup-time deprecation notice ("VMess (with no Forward Secrecy, etc.)") is printed whenever a VMess inbound or outbound is loaded (infra/conf/vmess.go:65, 124). VLESS with the new mlkem768x25519plus encryption is the recommended replacement.

Cross-core notes

• sing-box uses users[].uuid instead of clients[].id, and exposes alter_id (snake_case), global_padding, and authenticated_length options that Xray does not have. See VMess — sing-box.
• mihomo has a single proxy-object shape, uses the field name cipher for the security selector, and surfaces UDP-encoding switches (xudp, packet-addr, packet-encoding) on the outbound. See VMess — mihomo.

Source: infra/conf/vmess.go:18-120 · v26.9.9 (52a412d)