Xray Configuration File Explained: Inbounds, Outbounds, and Routing

Configuration Structure and Traffic Flow

Xray is the core that handles connections; v2rayN is the desktop client that manages nodes, generates configuration, and launches the core. A node share link usually describes just one remote connection, while native JSON can define local listeners, multiple outbounds, routing, and DNS. Saving a share link as config.json does not turn it into a runnable core configuration.

This is the main path to follow when reading a configuration. log records status, while dns comes into play when a domain needs resolving; neither is a separate forwarding hop every request must pass through. The order of top-level objects in the JSON does not determine traffic flow.

• inbounds: where traffic enters and which local protocol it uses.
• outbounds: how connections leave the core—direct, proxied, or blocked.
• routing: which outbound tag to use based on the source and destination.
• dns: configures built-in DNS; whether it is used also depends on related resolution settings.

Complete JSON Example: Local Inbounds and Direct Outbound

Here’s a standalone configuration for understanding the structure. The SOCKS inbound listens on 127.0.0.1:10808, and the HTTP inbound listens on 127.0.0.1:10809. There’s no remote proxy node: ordinary requests connect directly, while requests to the reserved test domain blocked.test are blocked. This configuration cannot be used to verify a remote proxy.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    },
    {
      "tag": "http-in",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "UseIP"
      }
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": [
          "full:blocked.test"
        ],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "ip": [
          "127.0.0.0/8",
          "10.0.0.0/8",
          "172.16.0.0/12",
          "192.168.0.0/16"
        ],
        "outboundTag": "direct"
      }
    ]
  },
  "dns": {
    "servers": [
      "localhost"
    ]
  }
}

This example uses strict JSON: keys and strings are double-quoted, comments aren’t allowed, and there’s no trailing comma after the last array element. The field notes below explain this configuration; you don’t need to assemble them into a second configuration.

log: Pinpoint Where Errors Occur

loglevel controls how much detail error logs include. Common values are debug, info, warning, error, and none. For troubleshooting, temporarily change warning in the example to info, then switch it back to avoid keeping excessive connection details in your logs.

This example doesn’t specify log file paths, so start by checking the console when running from the command line. If you add access or error, choose a path the current process can write to, and account for relative paths and the working directory. Logs may include destinations, so remove sensitive information before sharing them for troubleshooting.

• JSON parsing error before startup: check brackets, commas, and field types first.
• address already in use at startup: check the local port before changing the remote protocol.
• The inbound accepts the request, but the connection later times out: check the actual outbound, DNS resolution, and destination reachability.

inbounds: Listen Address, Port, and Inbound Tag

Each inbound object defines a listener that receives traffic. listen is the bind address, port is the listening port, and protocol determines which protocol the app uses to connect. tag is an identifier within the configuration—not a password or hostname to enter in a browser.

127.0.0.1 accepts connections only from the local machine. Changing it to 0.0.0.0 broadens the IPv4 listening scope; whether other devices can connect still depends on the firewall and network environment. This example uses noauth for SOCKS, so don’t expose the listener more widely just to try sharing it on a local network.

• When a browser uses the system proxy settings, point it to the actual HTTP inbound. Don’t mix up the two ports.
• The local port isn’t the remote server port; changing 10808 won’t change the node’s server-side configuration.
• udp: true enables UDP on the SOCKS inbound only; it won’t make the HTTP inbound carry regular UDP traffic.

outbounds: Outbound Protocols and the Default Outbound

outbounds is an array of outbounds available to routing. In this example, freedom connects directly to the destination, while blackhole blocks the connection. direct and block are user-defined tags here; behavior is determined by protocol, not by what the tag name means in English.

When adding a remote proxy outbound, the protocol, server address, port, identity parameters, and transport settings must all match. Simply changing freedom to vless does not configure a working node. TLS or REALITY fields belong in the relevant transport security settings; don’t put them in the inbound SOCKS settings.

routing: Rule Order, Tag References, and Resolution Strategy

Rules in routing.rules are checked in array order, and the first matching rule determines the outbound. The first rule in this example sends the exact domain blocked.test to block; the second sends the listed IPv4 ranges to direct. These ranges are examples, not a comprehensive set of special-use addresses, and they don’t include IPv6.

1. After a request arrives, the core gets the available information, such as the inbound tag, destination domain or IP, and port.
2. Check rules in order, starting with the first. Different condition types within the same rule generally all need to match.
3. Items in the same list are generally matched with an “any” condition—for example, any range in the ip array can match.
4. When a rule matches, its outboundTag is used; if none match, the default outbound is used.

full: matches an exact domain, while domain: matches a domain and its subdomains. To scope a rule to a particular inbound, add an inboundTag array. Referenced tags must match the tag on the corresponding object. Inbound and outbound tags serve different purposes; you can’t reference socks-in as an outbound.

This example uses AsIs, so requests submitted as domains aren’t resolved just to match the second IP rule. However, the default outbound is still direct, so seeing a request connect directly doesn’t prove it matched the private IP range rule. When troubleshooting, check the actual rule match and outbound—not just whether the page loads.

dns: Distinguish Routing Resolution from Connection Resolution

Configuring dns doesn’t mean Xray takes over DNS for every app. An app may resolve a domain itself and then pass the IP to the proxy, or send the domain to a SOCKS or HTTP inbound. What information routing can use depends first on what the inbound actually receives.

In this example, dns.servers uses the special value localhost, which means resolution goes through the local system resolver—not a DNS server running on the local machine. It also doesn’t open a UDP port 53 listener. To provide DNS service to apps, you need to design a separate inbound for DNS requests and configure how they’re handled.

• routing.domainStrategy: determines whether routing needs to resolve domains to IP addresses for rule matching.
• freedom.settings.domainStrategy: determines how the direct outbound handles destination domains.
• dns.servers: provides resolvers for built-in DNS; related features determine when they’re used.

This example sets UseIP on the freedom outbound, so direct connections resolve domains through the built-in DNS process. This doesn’t conflict with AsIs for routing: the former applies when the outbound prepares to connect, while the latter governs rule matching. Even if the outbound later gets an IP, routing isn’t automatically run again after its decision has been made.

Testing and Troubleshooting: From Config Checks to Live Connections

First validate the configuration with the core’s built-in check command, then start the listeners, and finally connect an app. Run the commands below in a terminal where the xray executable is available. If it isn’t on your command search path, use its actual path. Check the version and help output first to confirm which options the current binary supports.

xray version
xray run -help
xray run -test -config ./config.json
xray run -config ./config.json

A successful config check only means the core accepts the configuration; it doesn’t mean a remote server is reachable or that an app is using the proxy. For a repeatable local test, start a test server in another terminal, then access it through each inbound:

python -m http.server 8000 --bind 127.0.0.1

curl --noproxy "" --proxy socks5h://127.0.0.1:10808 http://127.0.0.1:8000/
curl --noproxy "" --proxy http://127.0.0.1:10809 http://127.0.0.1:8000/

This test requires Python and curl installed on the local machine. The response comes from a local test directory, verifying the chain from app to inbound, routing, and direct outbound. --noproxy "" prevents existing proxy bypass settings from skipping this inbound test. Stop the temporary server when you’re done; a directory listing in the terminal isn’t a proxy speed test.

Once the baseline test works, add a remote proxy outbound and configure an explicit route for it. Change one thing at a time and keep the last working configuration. If something breaks, you can narrow the cause to the inbound, rules, resolution, or remote connection instead of repeatedly changing unrelated settings.