How to Configure V2Ray VMess Protocol: Complete Server and Client Setup

You configure the V2Ray VMess protocol by defining a server-side inbound listener in v2ss/server-cfg/v2/config.json with a UUID and transport settings, then generating a Base64-encoded vmess:// URL that client applications like V2RayU or V2RayN import to establish encrypted connections.

The V2Ray VMess protocol serves as the core default transport throughout the bannedbook/fanqiang repository, handling encrypted communication between clients and servers. Proper configuration requires editing the server JSON to define authentication and network parameters, then creating matching client URLs that encode these credentials according to the parsing logic found in V2RayFmt.kt.

Understanding the V2Ray VMess Architecture

Server-Side Inbound Configuration

The server configuration resides in v2ss/server-cfg/v2/config.json, where the inbounds array defines the VMess listener. This configuration specifies the listening address, port, and client UUIDs under settings.clients, alongside streamSettings that determine the transport layer.

Client-Side VMess URL Structure

Clients consume the protocol through vmess:// URLs containing Base64-URL-safe encoded JSON. According to the implementation in fqnews2/app/src/main/java/io/nekohasekai/sagernet/fmt/v2ray/V2RayFmt.kt, these URLs decode into VmessQRCode objects that map directly to VMessBean structures, supplying fields such as address, port, uuid, network, tls, host, and path.

Server Configuration (config.json)

To configure the V2Ray VMess protocol on the server, edit v2ss/server-cfg/v2/config.json to define the inbound listener with your specific UUID and transport settings.

{
  "inbounds": [
    {
      "listen": "0.0.0.0",
      "port": 1234,
      "protocol": "vmess",
      "settings": {
        "clients": [
          { "id": "7966c347-b5f5-46a0-b720-ef2d76e1836a" }
        ]
      },
      "streamSettings": { "network": "tcp" }
    }
  ],
  "outbounds": [
    { "protocol": "freedom", "tag": "direct" },
    { "protocol": "blackhole", "tag": "block" }
  ]
}

The streamSettings.network field accepts values like tcp, ws (WebSocket), or grpc to adapt to different transport layers. Outbound handlers typically use freedom for direct traffic and blackhole for blocking private IP ranges, routing traffic according to simple rules defined in the routing section.

Generating the VMess URL

Client configuration requires a VMess URL constructed from a JSON object containing server parameters. The syntax follows vmess://BASE64_JSON where the payload uses URL-safe Base64 encoding (replacing + with -, / with _, and removing = padding).

#!/usr/bin/env bash
UUID="7966c347-b5f5-46a0-b720-ef2d76e1836a"
cat <<EOF | base64 -w0 | sed 's/+/-/g; s/\//_/g; s/=//g'
{
  "v": "2",
  "ps": "My V2Ray Server",
  "add": "mydomain.me",
  "port": "1234",
  "id": "$UUID",
  "aid": "0",
  "net": "tcp",
  "type": "none",
  "host": "",
  "path": "",
  "tls": ""
}
EOF

# Prepend "vmess://" to the output

The key configuration fields that must match between server and client include:

Field	Meaning	Typical Value
add	Server IP or domain	mydomain.me
port	Listening port (matching server inbound)	1234
id	UUID for authentication	7966c347-b5f5-46a0-b720-ef2d76e1836a
aid	Alter ID (legacy, often 0)	0
net	Transport network	tcp, ws, or grpc
type	Header type	none or http
host	Host header for WS/TLS	example.com
path	WebSocket path	/path
tls	TLS enablement	tls or empty
sni	Server Name Indication	example.com

Client Import and Configuration

macOS V2RayU Setup

For macOS users, the repository's macos/V2RayU.md documentation specifies importing configurations through the "订阅设置" (Subscription Settings) screen. Right-click the V2RayU menu icon, select subscription settings, and paste the complete vmess:// URL into the designated input field. The application automatically parses the Base64 payload and configures the connection.

Windows V2RayN Configuration

Windows users following windows/V2RayN.md should utilize the "URL方式" (URL Method) input box. Paste the VMess URL directly into this field to automatically populate the server address, port, UUID, and transport parameters. The GUI will display "已连接" (connected) upon successful verification.

Android and iOS Parsing Logic

The mobile implementation in fqnews2/app/src/main/java/io/nekohasekai/sagernet/fmt/v2ray/V2RayFmt.kt handles URL parsing through the decodeBase64UrlSafe() method. The Kotlin code extracts the substring after vmess://, decodes the Base64 payload into a VmessQRCode object, then maps these fields to a VMessBean instance:

// V2RayFmt.kt – decode a vmess URL
val result = link.substringAfter("vmess://").decodeBase64UrlSafe()
val vmessQRCode = Gson().fromJson(result, VmessQRCode::class.java)
bean.apply {
    serverAddress = vmessQRCode.add
    serverPort = vmessQRCode.port.toInt()
    uuid = vmessQRCode.id
    alterId = vmessQRCode.aid.toInt()
    type = vmessQRCode.net
    host = vmessQRCode.host
    path = vmessQRCode.path
    // TLS handling…
}

Additionally, fqnews2/app/src/main/java/moe/matsuri/nb4a/proxy/shadowtls/ShadowTLSBean.java extends StandardV2RayBean, reinforcing that VMess operates as the default protocol bean within the application's proxy hierarchy.

Summary

• Server setup requires editing v2ss/server-cfg/v2/config.json to define a VMess inbound with a unique UUID and streamSettings specifying the transport network.
• URL generation involves Base64-URL-safe encoding of JSON containing add, port, id, net, and tls fields to create the vmess:// link.
• Desktop clients import URLs through V2RayU's subscription settings (macOS) or V2RayN's URL input method (Windows).
• Mobile parsing occurs in V2RayFmt.kt, which decodes URLs into VMessBean objects for Android and iOS connectivity.
• UUID consistency between the server's config.json and the client's URL is essential for authenticated connections.

Frequently Asked Questions

What is the exact VMess URL format?

The VMess URL format is vmess:// followed by a Base64-URL-safe encoded JSON object. This encoding replaces standard Base64 characters (+ becomes -, / becomes _, and = padding is removed) to ensure safe transmission via clipboard and QR codes. The JSON payload must include fields like add (server address), port, id (UUID), net (network type), and optional TLS settings.

Where is the server configuration file located in the fanqiang repository?

The server configuration file is located at v2ss/server-cfg/v2/config.json according to the bannedbook/fanqiang source code. This JSON file contains the inbounds array defining the VMess listener, including the protocol type, client UUIDs, and stream settings for transport layers such as TCP or WebSocket.

How does the Android client parse the VMess URL?

Android clients parse the VMess URL in fqnews2/app/src/main/java/io/nekohasekai/sagernet/fmt/v2ray/V2RayFmt.kt using the decodeBase64UrlSafe() method to decode the payload into a VmessQRCode object. The Kotlin code then maps these fields to a VMessBean instance, configuring the underlying V2Ray connection with the appropriate server address, port, UUID, and transport-specific parameters like WebSocket host and path.

Which transport networks does the VMess configuration support?

The configuration supports multiple transport networks specified in the streamSettings.network field on the server and the net field in the client URL. Supported values include tcp for standard transmission, ws for WebSocket tunneling to bypass restrictive firewalls, and grpc for gRPC transport. Each network type may require additional parameters such as host, path, or TLS SNI settings to function correctly across different network environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}