V2Ray Config JSON Explained: inbounds, outbounds, and routing

Explore V2Ray config sections in order, from log and inbounds to outbounds, routing, and DNS. Learn how tags connect, how rules are evaluated, and how common fields work with practical examples.

At a glance

When you get a JSON file generated by a client, first identify which section accepts requests, which selects a route, and which establishes the connection. This guide uses local SOCKS and HTTP inbounds to show how tags connect to routing rules, then explains the difference between DNS lookups during routing, outbound resolution, and lookups performed by the app itself. The example ports are illustrative, not client defaults.

log: logging and config structure

The top level is a JSON object. In the examples here, log, routing, and dns are objects, while inbounds and outbounds are arrays—even when there is only one item. The order of top-level keys does not determine the request path, but array order can matter: rules are evaluated in sequence, and requests that match no rule usually go to the first outbound.

App requestLocal inboundRule matchingOutbound selectionDestination connection
{
  "log": {
    "loglevel": "warning"
  }
}

This is only a logging snippet. For troubleshooting, temporarily set loglevel to info, reload the config, and reproduce the issue once in the same app. After collecting enough detail, restore warning. Set access and error to specify output files for the corresponding logs, but a config loading successfully does not mean the log directory is writable. If the issue occurs during startup, check the client or startup process messages instead of waiting for access logs. Before sharing logs, redact subscription URLs, authentication fields, and any connection details you should keep private.

inbounds: listen address, local port, and tags

The inbound listen and port fields set the listening address and port. protocol determines which proxy protocol the app must use, and settings are interpreted by that protocol. Entering an app's HTTP proxy settings for a SOCKS port will not complete the expected handshake, even if the port is listening. Both examples below listen only on the loopback address and are not exposed to your local network.

10808
Example SOCKS listening port
10809
Example HTTP listening port

SOCKS inbound

listen
127.0.0.1
port
10808
protocol
socks
tag
local-socks

Enter this port in the app's SOCKS proxy settings.

HTTP inbound

listen
127.0.0.1
port
10809
protocol
http
tag
local-http

Enter this port in the app's HTTP proxy settings.

Check the listener before changing routing

If a connection to the local port is refused, first confirm that the core is running, no other process is using the port, and the app's address matches the actual listening address. If the request has not reached the core, increasing a routing rule's priority will not help.

outbounds: proxy protocols and the default route

An outbound's protocol determines how an accepted destination connection is handled. freedom is used for direct connections, while blackhole blocks traffic. tag is a reference name within the config, not a protocol: naming a tag direct does not enable direct connections. The protocol in that same outbound determines its behavior.

{
  "outbounds": [
    {"tag": "direct", "protocol": "freedom", "settings": {}},
    {"tag": "blocked", "protocol": "blackhole", "settings": {}}
  ]
}

routing: tag references and rule order

routing.rules are checked from top to bottom, and the first matching rule determines where traffic goes. inboundTag is an array of inbound tags; outboundTag is a single outbound tag string. When a rule includes multiple match fields, the request must satisfy all of them. The first rule below blocks requests from the SOCKS inbound only when the destination domain is exactly example.org. The second sends other SOCKS requests directly.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "domain": ["full:example.org"],
        "outboundTag": "blocked"
      },
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}
Connection methodDestination seen by the coreExpected outbound
SOCKSexample.orgRule 1: blocked
SOCKSwww.example.orgRule 2: direct
HTTPexample.orgNo match: first outbound, direct

If you swap the two rules, the former second rule will catch all SOCKS requests first, leaving the exact-domain rule with no chance to match. If you swap the outbounds but keep the rules in place, requests with an explicitly assigned tag still follow the same route, but unmatched HTTP requests will use the new first outbound. When troubleshooting misrouted traffic, check the order of both arrays separately; the default outbound is not the last routing rule.

dns: routing lookups vs. app lookups

The top-level dns configures the core's built-in DNS, not the operating system's global DNS settings. Adding dns.servers alone does not automatically take over every app's DNS queries. If an app resolves a domain first and passes only the destination IP to the proxy, routing cannot recover the original domain from that IP alone. Without other domain information, the exact-domain condition above will not match.

{
  "dns": {
    "servers": ["localhost"]
  }
}

Here, localhost uses the machine's own DNS resolution, making it easy to reuse the existing system configuration. It does not start a DNS service on a local port or determine which outbound the final connection uses. To verify a domain-based rule, first check whether the test request passes the domain to the inbound or whether the app has already replaced it with an IP address.

Troubleshoot config issues: check startup, inbound, routing, and outbound

  1. First, check which file is actually loaded. Strict JSON uses double quotes, and the final item must not have a trailing comma. The code blocks above show separate top-level fields; do not concatenate them into multiple root objects. If an error points to a field, check its type and whether the core supports it—even if the file is valid JSON.
  2. Understand the boundary between the core and client settings. In the v2rayN desktop app, check the local listener settings under Settings → Parameter Settings; the exact section may vary by version. Android v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Similar basic fields do not mean that extension fields are interchangeable. On Android, traffic handled through the VPN cannot be inferred from desktop system proxy settings.
  3. Change just one setting in the same test app at a time. First verify a regular request using the correct port, then test the blocked destination. If the result changes after switching the app to an HTTP proxy, check the inbound tag first. If domain and IP requests behave differently on the same inbound, check which form of the destination the app passes to the core.
  4. Check the outbound connection last. Matching the expected tag confirms that the right route was selected; it does not guarantee the destination is reachable. If a direct connection fails, check local DNS resolution and destination reachability. If a remote outbound fails, verify the remote port, protocol settings, and transport configuration. Change one thing at a time, reload, and repeat the same test to identify which change affected the result.
Download clientsChoose v2rayN or v2rayNG for your platform