Configuration Reference
V2Ray JSON Configuration Guide
If you haven't installed the client, imported a profile, and made your first connection yet, start with the quick start guide and follow the steps in the graphical interface. Come back here when you need to see which fields a setting generates or trace where a connection went wrong. Using local listening, direct connections, and blocking as examples, this guide explains the configuration passed from the client to the core.
JSON structure: from entry to exit
The configuration root is an object. Think of it as a connection blueprint the core reads at startup, not a field-by-field copy of the client interface. inbounds and outbounds are arrays, so one process can define multiple entry points and exits; routing, dns, and policy are objects with separate responsibilities. Subscription names, interface preferences, and past speed test results stored by the client aren't part of this blueprint. Before exporting, check whether you're exporting client settings, a single node, or the complete file passed to the core for a particular launch.
Complete baseline vs. partial examples
The following is a complete local baseline: the app sends SOCKS requests to a loopback address, and the core connects directly to the destination through the freedom outbound. This isn't a remote node configuration, so it needs no server address or account. Load a copy through the client's supported custom configuration option. If another process is using the same port, exit that process or change the port in your copy and update the test app's proxy address. Code snippets in later sections usually show individual fields; don't append them one after another to this file.
{
"log": {
"loglevel": "warning"
},
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": {
"auth": "noauth",
"udp": false
}
}
],
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
}
]
}
Three details are worth checking. First, port is a number and udp is a boolean; don't quote them just for consistency. Second, both inbounds and outbounds have protocol and settings, but each protocol defines how its settings work. You can't copy authentication fields from a SOCKS inbound to a direct outbound. Third, tag is an identifier within the file. You can choose its name, but every later reference must match it exactly. Renaming direct won't change its behavior, but rules that still reference the old name may stop working.
Read the connection flow, not just the field order
When troubleshooting, trace the connection in order: the app sends a request to an inbound, the core determines what it can learn about the destination, then selects an outbound based on the rules. The outbound establishes the next connection using its own protocol and resolution behavior. DNS isn't a fixed step in the middle of every connection. If a request already contains an IP address, the core may not need a lookup. If the app resolves the name locally before sending the request through SOCKS, the core may never see the original domain. Connection policies control waiting and statistics at certain stages; they don't select a route.
The order of fields in the root object usually doesn't affect their meaning. Moving the log block to the end of the file, for example, doesn't change which connections it covers. Array order can affect results: routing rules are checked in order, and the first outbound in the array is the default. Handle objects and arrays separately when combining configurations. If the root already has outbounds, edit that array instead of adding another key with the same name. Many parsers keep the later value without reporting duplicate keys, which can make the original outbounds disappear at startup.
Know where to make changes: client or core
For desktop, v2rayN is a good starting point. Choose a package for your operating system and processor architecture on the client downloads page. On Android, choose v2rayNG or v2flyNG based on the core you need. A graphical client may regenerate its standard configuration when you switch nodes, restart the service, or update a subscription. Editing a temporary file may work briefly, but that doesn't mean the change was saved. First check whether the client is using graphical settings or a custom configuration. Save changes through the relevant option, then reopen or re-export the configuration to confirm they're still there.
Before making changes, save a copy you can restore exactly and note which core the client uses. The same field may not offer the same options across different cores or configuration variants. A snippet opening in a text editor doesn't mean the current core will accept it. Strict JSON requires double quotes and doesn't allow comments, trailing commas, or single quotes. Check syntax first, then field types and local listeners, and finally test a real request. This helps distinguish a file the core can't read from a service that didn't start or a connection that behaved unexpectedly.
inbounds: listen address, port, and protocol
An inbound describes how the core accepts connections, not where a remote server is. To check whether an inbound is usable, make sure the listen address, port, and inbound protocol all match. A client showing “connected” doesn't ensure the app is using the right settings: it may still be using an old proxy port or sending a SOCKS handshake to an HTTP proxy. To tell these cases apart, first check whether the operating system can connect to the port, then check whether the core received the expected proxy request.
Set up separate SOCKS and HTTP entry points
This snippet can replace the baseline inbounds array. It assigns a separate port to each proxy type, making it easier to see which entry point an app is using. Use local-socks for apps that explicitly support SOCKS and local-http for apps that support HTTP proxies. Both can use the same outbound, or you can route them separately by inbound tag. A port number doesn't determine the protocol; protocol sets the handshake format.
{
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": {
"auth": "noauth",
"udp": false,
"userLevel": 0
}
},
{
"tag": "local-http",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {
"userLevel": 0
}
}
]
}
| Field | Purpose | Check |
|---|---|---|
listen | Restricts the local address the listener binds to. | The address portion of the proxy address. |
port | Sets the inbound port. | The app's proxy port and whether the port is already in use. |
protocol | Determines which proxy handshake the inbound accepts. | The proxy type selected in the app. |
tag | Tags the traffic source for routing rules. | inboundTag in a rule. |
Loopback addresses, access scope, and address families
127.0.0.1 is the local IPv4 loopback address. The example has no account configured, but still limits the listener to the local machine so other devices can't use it directly. Don't bind to all network interfaces just to let a browser on the same machine connect. That broadens access without fixing a mismatched proxy type. If an app runs in a virtual machine or another network namespace, its loopback address may refer to its own environment, not the host. Don't assume the host's proxy address will work there.
When a local app uses localhost, the system may try the IPv6 loopback address first. The example binds only to IPv4, and some apps can't fall back, so even local connections may fail. For troubleshooting, enter 127.0.0.1 explicitly to rule out name resolution and address-family selection before deciding whether to add another listener. If the startup log says the port is already in use, find out which process owns it first; changing the listen address shouldn't be the default fix. An old process left running by a client may still be handling connections for another app.
UDP support and domain detection are separate
Allowing UDP on a SOCKS inbound doesn't mean every UDP datagram will reach the core. The app must support SOCKS UDP relay, and the outbound must be able to handle that traffic. A standard HTTP proxy won't take over UDP from the system. Start connectivity tests with TCP. Test UDP separately only when you know which app and protocol need it, ideally in a controlled environment. A working webpage doesn't prove that an app's calls, games, or traditional DNS requests use the same route.
Some inbounds can identify destination details in traffic before setting up the next connection. This is commonly configured with sniffing. It may recover a domain the app didn't provide, but it can't turn every IP address into a unique website. Detection depends on the traffic, and whether the detected name replaces the destination is a separate setting. For debugging, start with an app that sends the domain through the proxy and confirm ordinary domain rules work. Then decide whether detection is needed; don't enable several options at once and guess which one made the difference.
outbounds: outbound protocols and default behavior
An outbound describes what the core does with a request after receiving it. The easiest two outbounds to verify are freedom and blackhole: the first connects directly to the destination from the machine running the core, while the second terminates the traffic sent to it. Naming an outbound direct or blocked doesn't give it any special behavior; that comes from protocol. Start with these two clearly different outcomes to confirm routing, then add connections that require a remote server. This helps separate routing issues from node handshake failures.
Compare two outbounds with clear, observable results
{
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {
"domainStrategy": "AsIs"
}
},
{
"tag": "blocked",
"protocol": "blackhole",
"settings": {
"response": {
"type": "none"
}
}
}
]
}
This snippet can replace the baseline outbounds array. Since direct is first, connections that don't match a rule use it. An outbound that blocks traffic won't automatically handle any domains just because it's in the array; a rule must send requests to it, or you must make it the default. response.type set to none means no protocol response is generated. The app may show a closed connection, a loading error, or a retry rather than a page explaining why the request was blocked. After a failure, check the log to see which outbound was selected; the failure alone doesn't prove the blocking rule worked.
The first outbound is the default, so moving items in the list can affect services not covered by a rule. During testing, keep the default explicit and add a rule for just one test target at a time. If you make blocking the default, maintain a separate allowlist; the second outbound won't automatically take over if the first one fails. Backup nodes and failover need an explicit selection mechanism. A plain outbound array doesn't define a retry order.
Keep protocol and transport settings separate
Remote outbounds usually include settings and streamSettings. The former contains parameters defined by the proxy protocol; the latter typically describes the transport and security layers used to connect to the server. The server address, port, protocol, and identity details must match the server. Check transport type, path, host name, and security requirements together as well. Matching protocol names alone don't guarantee compatibility. A domain can host multiple services, and the name on a certificate may differ from the address used to connect.
After importing a subscription, use the subscription import guide to check which protocol and transport the client detected. Don't combine familiar-looking fields from different nodes. To check whether the current core supports an option, see Xray vs. V2Fly core differences. After changing cores in the graphical interface, restart the actual connection and check the startup information. Changing the name in a dropdown doesn't prove the running process has switched.
Distinguish the destination from the server address
The destination in an app's request is the service it wants to reach. The server address in a remote outbound is a different endpoint the core connects to first. Both may be domains, but they're resolved in separate steps. With a direct outbound, AsIs preserves the address as given for the dialing stage; it doesn't tell the built-in DNS resolver to look up every destination. With a remote outbound, check separately that the local machine can connect to the server and that the server can reach the final destination. A website failing to load doesn't prove the server address is wrong, and seeing an outbound selected doesn't prove the destination returned data.
When a connection times out, note which outbound was selected, where it connects, and which stage it reached. If the direct baseline fails too, check the local network and destination service first. If only one remote outbound fails, look at its transport and handshake. When following the v2rayN node timeout checklist, test the same destination each time. Changing the destination, core, and node together makes it impossible to tell which change caused the difference.
routing: match order and destination details
Routing rules decide which defined outbound handles a request; they don't change its proxy protocol. Rules are checked in order, and the first match wins—later rules of the same kind aren't evaluated as a fallback. Put precise exceptions before broader rules. If a rule that matches every request is at the top, even a complete domain list below it has no effect. Plan the default outbound too: a request that matches no rule still goes somewhere, namely the first outbound in the array.
Write a rule you can test on its own
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"domain": ["full:example.org"],
"outboundTag": "blocked"
},
{
"type": "field",
"inboundTag": ["local-socks"],
"outboundTag": "direct"
}
]
}
}
Add this snippet to a configuration with direct and blocked outbounds already defined, and keep the local-socks inbound. The first rule requires the request to come from that inbound and its destination domain to match example.org exactly. The second covers all other traffic from that inbound. If there's also an HTTP inbound, it won't match either rule's source condition and will use the default outbound. Swap the two rules and every SOCKS inbound request will match the second rule's broader condition first, leaving the exact-match rule no chance to run.
Different condition fields in the same rule must all match; multiple candidate values for one field provide alternatives. For example, adding network set to TCP means the network type must match too—it doesn't mean “from this inbound or using TCP.” To match either of two separate scenarios, write two rules that point to the same outbound. Don't merge independent rules just to shorten the file; that can turn a union of match conditions into an intersection.
Match by domain or by IP address
full: matches an exact domain and doesn't include subdomains. To cover both a root domain and its subdomains, use domain: and test a similar-looking name that should not match. A bare string can match more broadly than expected, so it isn't suitable for expressing “this domain only.” Use regular expressions only when needed, and avoid broad patterns that also capture similar names. IP rules need a numeric address or subnet, not a domain. If a rule references a domain or IP list, make sure the current core can locate the resource and that it contains the category you're using.
routing.domainStrategy determines whether domain names are resolved to IP addresses for routing matches. AsIs uses only the destination details already available, so an IP rule won't trigger a lookup by itself. IPIfNonMatch can look up an address when nothing matched initially, but a broad domain rule that matches first may prevent an IP rule from running. IPOnDemand may look up an address as soon as an IP condition is checked. Don't treat these strategies as performance presets. First decide whether you need to classify by domain or by resolved IP address.
Testing a non-match matters more than testing a match
After changing rule order, test at least one host that should be blocked, an unrelated host that should go direct, and a similar-looking subdomain that should be excluded. If the app resolves a domain to an IP before passing it to the proxy, an exact-domain rule can't match without additional detection information. Browsers may also reuse existing connections or load resources from several hosts. A single, isolated request is easier to interpret than the result of loading a whole page.
If the expected outbound was selected but the request still fails, leave the routing rule as is and investigate the outbound, DNS, or destination service. If an outbound tag is misspelled, check the outbound definition and rule instead of adding a duplicate outbound just to match the typo. For configurations you maintain long term, put a few precise exceptions at the top, group the rest by purpose, and make the default route explicit. Each change should have a clear set of targets it affects—and targets it shouldn't affect.
V2Ray DNS Configuration: who resolves names, and where
When domain resolution fails, first find out who made the query. A browser or the operating system may resolve the name before connecting to the proxy. The core may use its built-in resolver for routing matches or outbound dialing, and a remote server may handle the final lookup. The dns object configures the core's own resolver; it doesn't automatically replace the operating system's DNS or force every app to stop resolving names on its own. If you change it but the client log shows no corresponding query, the test request probably never reached this layer.
Test the core's resolver with a fixed mapping
This example is for local testing, not a general-purpose proxy configuration. Set up a local HTTP service bound to 127.0.0.1 on a port different from the proxy inbound, such as 8000. Start with the complete baseline from the structure overview, add the dns object shown here to the root, then replace outbounds. Send demo.test unchanged through SOCKS and visit http://demo.test:8000/. The service must accept that host name, or at least log the request it receives. This example maps a reserved test domain to loopback, so no external DNS server needs to resolve it.
{
"dns": {
"hosts": {
"demo.test": "127.0.0.1"
},
"servers": ["localhost"]
},
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {
"domainStrategy": "UseIP"
}
}
]
}
hosts is a static mapping for the core's resolver. localhost in servers means to use the local system's resolution capability for names that need a lookup; it doesn't require a DNS server listening on a loopback address. UseIP is set for the direct outbound here so it resolves the domain to an address and lets you observe the static mapping above. If the test app insists on resolving the name itself first, it may report that the domain doesn't exist. If it passes an IP to the core, a successful request won't prove the static mapping was used.
Don't confuse two fields with the same name
domainStrategy in the routing object controls how destination details are resolved for matching. The field with the same name in outbound settings controls how that outbound handles a domain before connecting. Changing the outbound strategy won't make the routing rules run again after a miss. Conversely, resolving an IP for routing doesn't guarantee the outbound will dial that same address; the result depends on the outbound implementation and configuration. When troubleshooting, change one layer at a time, then check the selected outbound and final destination. Don't attribute both changes to one switch.
If you use a specific DNS server, first make sure the core can reach it from the current network. Then consider domain-based server selection and fallback. Choosing a server by domain controls where the DNS query goes; it doesn't choose the outbound for the app's connection. They may be affected by different rules. If the DNS server is specified by domain, consider how its own name will be resolved initially. Depending on the same server before it can be reached can create a loop, causing lookups for many domains to time out.
Use the error type to decide what to check next
A nonexistent domain and a timed-out request are different errors. The first means a negative response was received and understood. The domain may be mistyped, the resolver may not recognize an internal domain, or a static mapping that should have matched may not have been used. A timeout means no usable response arrived in time; check the resolution path, network reachability, and server response. If a lookup returns an address but the connection still fails, check whether it's IPv4 or IPv6, whether the network can reach it, and whether a routing rule sent the request through another outbound.
If results are inconsistent, consider the app cache, system cache, core cache, and existing connections separately. Closing a tab may not end a connection held open by the browser, and changing the core configuration may not clear the app's DNS cache. Retest with a new, independent request and compare its recorded destination and result instead of judging by the number of refreshes. If system proxy settings are involved, see the connected but no internet troubleshooting checklist to isolate the entry-point issue before narrowing down DNS.
policy: handshakes, idle timeouts, and statistics
Policies don't choose which domain to access or which node to use, and they aren't the same as the system firewall. policy.levels defines connection settings for user levels recognized by the core; policy.system contains system-wide statistics switches. These levels aren't operating system account permissions or subscription tiers. Inbound or protocol user settings determine which level applies; the policy block defines its behavior. If a level doesn't seem to take effect, first check which inbound the connection uses and whether the protocol applies that level.
Set clear timeout limits for a test inbound
{
"policy": {
"levels": {
"0": {
"handshake": 8,
"connIdle": 300,
"uplinkOnly": 5,
"downlinkOnly": 5
}
},
"system": {
"statsInboundUplink": true,
"statsInboundDownlink": true
}
},
"stats": {}
}
Add these two top-level fields to the configuration and test with the SOCKS inbound from earlier, which sets userLevel: 0. The keys under levels are level numbers written as strings; time values are numbers in seconds. These values are examples for discussion, not universal recommendations. Which settings apply depends on the protocol implementation. Also distinguish a connection closed by the core while handling the inbound from one ended first by the remote server, app, or network device.
| Field | Stage | What you may observe |
|---|---|---|
handshake | The initial handshake for supported protocols. | The connection is established, but the handshake never completes. |
connIdle | No data is exchanged for a period of time. | The connection works while active but drops after sitting idle. |
uplinkOnly | How long the connection remains open in one direction after data flow ends in the other. | Only the client is still sending data to the destination. |
downlinkOnly | How long the connection remains open in one direction after data flow ends in the other. | The sender has finished but is still waiting to read the remaining response. |
Decide whether to change a timeout based on the connection stage
A handshake timeout that's too short may close a slow connection before negotiation finishes. Increasing it won't fix a wrong port, a destination refusing the connection, or mismatched protocol settings. An idle timeout isn't the total connection lifetime. A session that regularly transfers data isn't idle just because it has been open for a while. To test an idle timeout, note when the last data was exchanged and see whether the connection ends near the configured interval. Compare that with the app's and server's own idle timeouts.
Half-close timeouts are easy to mistake for upload or download speed limits. They actually control how long one direction stays open after the other has finished sending. For example, after a test program finishes sending a request and closes its sending side, the service may still need time to prepare the final part of its response. If the wait is too short, the full response may not arrive. But if the test program closes the entire connection, increasing this timeout won't make the app read the data again. Change one field at a time and retest with a request that reproduces the disconnect.
Statistics switches, access methods, and scope
stats enables the statistics component. The two switches in policy.system allow inbound traffic to be counted separately for upload and download. This example doesn't configure an external statistics endpoint or automatically add charts to the client interface. Whether the graphical client displays these values, how it reads them, and when it resets them depends on how it's integrated. User-level statistics require separate level settings and a protocol that can identify users. You can't divide the total traffic from an unauthenticated inbound among individual local apps.
When troubleshooting, compare like with like: a cumulative total isn't a rate, and inbound and outbound traffic counts may not match exactly. Readings before and after restarting the process aren't one continuous measurement; the client may also start a new process when switching configurations. If you only need to know whether a test reached an inbound, check the connection tag and logs first. If you enable detailed statistics or access logs for debugging, restore your usual settings afterward. Don't open an additional network listener just to read counters.
Configuration validation and troubleshooting
Good troubleshooting isn't about resetting every suspicious switch. Preserve the symptoms first, then make the smallest useful comparison. Note the active core, which configuration it loaded, the proxy entry point, and the test destination. If multiple clients or processes are running, make sure you're checking the log from the right one. Validate in order: the configuration loads, the port accepts connections, the request reaches the core, the expected outbound is selected, and the destination responds. If an earlier condition hasn't been met, later symptoms may not belong to this test.
Check parsing errors first, then listener failures
If the core can't load the file, start with the first relevant error in the startup log. If a line number is given, check the previous item's trailing comma and the surrounding brackets too. Parsers often report the first character they can't continue past, which isn't necessarily where the original mistake occurred. Valid JSON only proves the syntax is complete; it doesn't prove the protocol is supported, the port is available, or tag references are correct. If the client immediately disconnects after switching configurations, don't start by refreshing the subscription or running a speed test—check the startup error first.
After startup, don't rely only on seeing a process with the expected name. Check the address and port it's actually bound to and compare them with the test request. If the connection is refused, check for a missing listener, incorrect proxy address, address-family mismatch, or a process that started or stopped at the wrong time. If the local port accepts connections but the proxy handshake fails, check whether it's running SOCKS or HTTP. Another program may own the port even while the client interface shows the expected settings. The startup log and an actual request reveal which process is handling the connection.
Reproduce the issue with one request and narrow it down
If curl is installed on your system, use the following requests in a terminal to test the complete baseline. socks5h sends the domain name to the SOCKS proxy; --noproxy "" prevents proxy exclusions in the environment from bypassing the explicit proxy. In the routing example that sends example.org to a blocking outbound, the first request should fail. The second is a comparison that doesn't match the domain rule, but still needs local network access to the destination. The third tests the local mapping in the DNS section; set up the local service and load that section's configuration first. The three requests aren't expected to succeed with the same configuration.
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 https://example.org/
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 https://example.com/
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 http://demo.test:8000/
If an independent request works but the browser doesn't, check the browser's proxy mode, connection reuse, DNS settings, and system proxy exclusions. If both fail, start by checking the inbound tag and outbound route for the test in the log. Not seeing the request doesn't necessarily mean it never reached the core; the current log level or client display may not include access details. Temporarily change loglevel in the baseline to info and retry. If needed, check the core access log in the client, then restore your usual log level.
Make changes easy to retest and roll back
For a complex issue, start with a copy that has one inbound and one direct outbound. First confirm that the app can reach its destination through the local proxy. Then add routing rules that distinguish the outcomes, followed by DNS or connection policies as needed. Test the remote outbound last. After each change, retest with the same protocol, port, and destination, and keep one request that shouldn't be affected. If a new error appears, undo only the last change and check whether the issue goes away. This gives you useful evidence about cause and effect, not just a connection that happened to work once.
Keep troubleshooting notes to five items: inbound, destination, outbound, stage, and result. When reporting an issue, include the error type, relevant tags, and only the necessary configuration fields—don't post a full exported file. Remove subscription URLs, account details, internal addresses, and detailed access logs. If you've edited a configuration snippet, identify any names that are only for testing. For errors during remote transport, continue with the node timeout troubleshooting checklist. If you're just setting up an inbound and connection mode for the first time, the quick start guide is faster.