VMess — mihomo

mihomo speaks VMess on both sides. The outbound shape carries every transport (ws, http, h2, grpc), TLS, REALITY, ECH, and the two authentication-extension toggles. The inbound is purposefully thinner — the user list lives directly on the listener.

Outbound

Entry under proxies: with type: vmess. The struct embeds BasicOption (common outbound fields: interface-name, routing-mark, ip-version, dialer-proxy, …) documented on the Proxies page (Phase 3 catch-up).

Field	Type	Default	Allowed values	Description
name	string	(required)	<string>	Unique proxy name.
server	string	(required)	<host>	Upstream server hostname or IP.
port	int	(required)	<port>	Upstream server port.
uuid	string	(required)	<UUID>	User UUID accepted by the server.
alterId	int	0	0 | <int>	Legacy MD5-AEAD compatibility. Keep at 0 for the modern AEAD-only mode.
cipher	string	auto	auto | aes-128-gcm | chacha20-poly1305 | none | zero	Symmetric cipher. mihomo's name for `security`.
udp	bool	false	true | false	Allow UDP packets to be relayed through this outbound.
network	string	tcp	tcp | ws | http | h2 | grpc	Underlying transport.
tls	bool	false	true | false	Wrap the stream in TLS.
alpn	[]string	[]	h2 | http/1.1	ALPN list offered during TLS handshake.
skip-cert-verify	bool	false	true | false	Disable TLS certificate verification (test only).
fingerprint	string	(unset)	<SHA256 hex>	Pin the server's TLS certificate to this SHA-256 fingerprint.
certificate	string	(unset)	<PEM file path>	Client certificate (mTLS).
private-key	string	(unset)	<key file path>	Private key matching `certificate`.
servername	string	(unset)	<SNI>	Override the TLS SNI.
ech-opts	ECHOptions	(disabled)	ECHOptions	Encrypted Client Hello configuration.
reality-opts	RealityOptions	(disabled)	RealityOptions	REALITY client configuration.
http-opts	HTTPOptions	(unset)	HTTPOptions	Settings for `network: http`.
h2-opts	HTTP2Options	(unset)	HTTP2Options	Settings for `network: h2`.
grpc-opts	GrpcOptions	(unset)	GrpcOptions	Settings for `network: grpc`.
ws-opts	WSOptions	(unset)	WSOptions	Settings for `network: ws`.
packet-addr	bool	false	true | false	Use the legacy packet-addr UDP encoding.
xudp	bool	false	true | false	Use xudp encoding for UDP packets (modern default). Mutually exclusive with packet-addr.
packet-encoding	string	(use udp/xudp flags)	packetaddr | xudp	Explicit packet-encoding selector; overrides the boolean flags when set.
global-padding	bool	false	true | false	Pad all writes to a uniform length. Server must match.
authenticated-length	bool	false	true | false	Use the authenticated-length framing. Server must match.
client-fingerprint	string	(global)	chrome | firefox | safari | ios | edge | random | randomized	uTLS client-hello fingerprint.

Source: adapter/outbound/vmess.go:43-72 · pinned at v1.19.27 (5184081)

ws-opts

Field	Type	Default	Allowed values	Description
path	string	/	/<path>	WebSocket path.
headers	map[string]string	{}	{<header>: <value>}	Extra HTTP headers on the upgrade request.
max-early-data	int	0	<bytes>	Maximum bytes of early-data buffered before the WS handshake completes.
early-data-header-name	string	(unset)	<header name>	Header used to carry the base64-encoded early data when the server expects it.
v2ray-http-upgrade	bool	false	true | false	Use the V2Ray-style HTTP-upgrade transport instead of true WebSocket.
v2ray-http-upgrade-fast-open	bool	false	true | false	Send the client payload alongside the HTTP-upgrade request to save one RTT.

Source: adapter/outbound/vmess.go:94-101 · pinned at v1.19.27 (5184081)

grpc-opts

Field	Type	Default	Allowed values	Description
grpc-service-name	string	(required)	<name>	gRPC service name path.
grpc-user-agent	string	(unset)	<UA string>	Override the gRPC client User-Agent.
ping-interval	int	0	<seconds>	HTTP/2 PING frame interval. 0 disables.
max-connections	int	0	<int>	Max concurrent gRPC channels (mux fan-out).
min-streams	int	0	<int>	Minimum streams per channel before allocating a new channel.
max-streams	int	0	<int>	Maximum streams per channel.

Source: adapter/outbound/vmess.go:85-92 · pinned at v1.19.27 (5184081)

Inbound

Entry under listeners: with type: vmess. Embeds BaseOption (listen, port).

Field	Type	Default	Allowed values	Description
users	[]VmessUser	(required)	<VmessUser array>	Accepted clients.
ws-path	string	(unset)	/<path>	WebSocket path served on this listener.
grpc-service-name	string	(unset)	<name>	gRPC service name accepted on this listener.
certificate	string	(unset)	<PEM file path>	TLS server certificate.
private-key	string	(unset)	<key file path>	TLS private key.
client-auth-type	string	(none)	no-client-cert | request-client-cert | require-any-client-cert | verify-client-cert-if-given | require-and-verify-client-cert	Mutual-TLS client-auth mode.
client-auth-cert	string	(unset)	<PEM file path>	CA bundle accepted as client roots.
ech-key	string	(unset)	<ECH config>	Encrypted Client Hello material.
reality-config	RealityConfig	(disabled)	RealityConfig	REALITY server configuration.
mux-option	MuxOption	(disabled)	MuxOption	Multiplex settings (sing-style mux).

Source: listener/inbound/vmess.go:12-24 · pinned at v1.19.27 (5184081)

users[]

Field	Type	Default	Allowed values	Description
username	string	(unset)	<string>	Display name.
uuid	string	(required)	<UUID>	User UUID.
alterId	int	0	0 | <int>	Legacy MD5-AEAD compatibility.

Source: listener/inbound/vmess.go:26-30 · pinned at v1.19.27 (5184081)

Examples

Outbound — VMess over WebSocket with TLS:

proxies:
  - name: vmess-ws
    type: vmess
    server: example.com
    port: 443
    uuid: a3482e88-686a-4a58-8126-99c9df64b7bf
    alterId: 0
    cipher: auto
    udp: true
    network: ws
    tls: true
    servername: example.com
    ws-opts:
      path: /vm
      headers:
        Host: example.com

Outbound — VMess over gRPC with REALITY:

proxies:
  - name: vmess-grpc
    type: vmess
    server: example.com
    port: 443
    uuid: a3482e88-686a-4a58-8126-99c9df64b7bf
    alterId: 0
    cipher: auto
    network: grpc
    tls: true
    servername: www.cloudflare.com
    client-fingerprint: chrome
    reality-opts:
      public-key: <reality public key>
      short-id: <short id>
    grpc-opts:
      grpc-service-name: GunService

Inbound under listeners:

listeners:
  - name: vmess-in
    type: vmess
    listen: 0.0.0.0
    port: 443
    users:
      - username: alice
        uuid: a3482e88-686a-4a58-8126-99c9df64b7bf
        alterId: 0
    certificate: /etc/mihomo/server.crt
    private-key: /etc/mihomo/server.key

Notes

• mihomo's outbound uses cipher for the symmetric algorithm. Both Xray (security) and sing-box (security) call this field differently. Allowed values are otherwise the same: auto, aes-128-gcm, chacha20-poly1305, none, zero.
• Three different UDP-encoding switches are exposed on the outbound: udp (boolean — enable UDP relay at all), xudp / packet-addr (legacy boolean selectors), and packet-encoding (modern explicit selector). When packet-encoding is set, the boolean selectors are ignored.
• global-padding and authenticated-length mirror sing-box's global_padding / authenticated_length — both sides must agree.
• ws-opts.v2ray-http-upgrade swaps the WebSocket handshake for the V2Ray HTTP-upgrade transport; v2ray-http-upgrade-fast-open further saves an RTT by piggybacking the client payload.

Cross-core notes

• Xray is AEAD-only and removes alterId entirely; the field name is security (not cipher). See VMess — Xray-core.
• sing-box keeps alterId (called alter_id on the outbound, alterId on inbound users), uses security rather than cipher, and surfaces multiplex via a dedicated multiplex block. See VMess — sing-box.

Source: adapter/outbound/vmess.go:43-101 · v1.19.27 (5184081)