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

> Learn how to configure the V2Ray VMess protocol with this guide. Set up your server and client for secure, encrypted connections using UUID and transport settings.

- Repository: [如何翻墙/fanqiang](https://github.com/bannedbook/fanqiang)
- Tags: how-to-guide
- Published: 2026-08-10

---

**You configure the V2Ray VMess protocol by defining a server-side inbound listener in [`v2ss/server-cfg/v2/config.json`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/V2RayFmt.kt).

## Understanding the V2Ray VMess Architecture

### Server-Side Inbound Configuration

The server configuration resides in [`v2ss/server-cfg/v2/config.json`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/v2ss/server-cfg/v2/config.json) to define the inbound listener with your specific UUID and transport settings.

```json
{
  "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).

```bash
#!/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`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/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:

```kotlin
// 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`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/V2RayFmt.kt), which decodes URLs into `VMessBean` objects for Android and iOS connectivity.
- **UUID consistency** between the server's [`config.json`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/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`](https://github.com/bannedbook/fanqiang/blob/main/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.