Complete Configuration · JSON Reference

V2Ray Configuration Reference

For a first install, subscription import, or connection test, start with the quick setup in Getting Started. This page is a companion field guide: use a minimal config to understand the request flow, then find the section you need to change.

JSON Structure and Request Flow

Start with a Complete Minimal File

A config file consists of a single top-level object. Inbounds and outbounds are arrays because the core can accept traffic from multiple sources and maintain multiple routes out. Routing, DNS, and policy are usually separate objects. They do not run one after another in the order they appear in the file; each comes into play at a different point when a request is processed. A section being present in the file does not mean every request uses it.

This complete example opens a single local SOCKS inbound and uses a direct outbound. It lets you check whether an app can send a request to the core and whether the core can then connect to the destination. No remote server or account is required, and this is not necessarily the default configuration after installing a client. Before loading this file in a UI that supports custom core configs, make sure another configuration is not already using the local port. Set the app to SOCKS5; this inbound is not an HTTP proxy.

{
  "log": { "loglevel": "warning" },
  "inbounds": [
    {
      "tag": "app-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": { "auth": "noauth", "udp": false }
    }
  ],
  "outbounds": [
    { "tag": "direct", "protocol": "freedom" }
  ]
}

Requests first arrive at an inbound, which interprets the protocol and extracts the destination the app wants to reach. With no routing rules, this config sends requests to the first outbound in the list. The direct outbound then connects from the current device. Whether the destination is reachable still depends on the device's network. Reaching it successfully confirms only this local path; it does not show that a separate remote outbound will work.

Field Types, Tags, and Config Snippets

Put field names and strings in double quotes. Ports in the examples are numbers, and switches use Boolean values. Objects and arrays use different brackets, and the last item has no trailing comma. Do not define the same field twice in one object. Some parsers accept duplicate fields and use the last value, making earlier changes appear to have no effect. Keep the file as standard JSON; even if a core accepts extensions, relying on them can make the config harder to import across clients.

FieldTypePurpose
inboundsArrayAccepts app requests
outboundsArraySends or rejects requests
routingObjectSelects an outbound based on conditions
dnsObjectConfigures the core's built-in DNS resolver
policyObjectSets connection behavior and statistics options

Tags are names used inside the config, not display names shown in a window. When a routing rule specifies a target tag, the core looks up the outbound by that string. Give inbounds and outbounds distinct, descriptive tags to avoid changing the wrong reference when renaming one. For example, after renaming a direct outbound, check for routing rules that still refer to its old name instead of checking only whether the new name appears in the outbound array.

The short examples below are snippets to merge into a complete file, not extra top-level objects to append to the original. Before replacing an array, check whether the app still uses any inbound in it. The config may also contain sections generated by the client for interfaces or statistics. Keeping those sections is safer than overwriting the whole block, especially if you still use the UI to switch servers.

Distinguish subscription data, options saved by the client, and the config ultimately loaded by the core. A subscription usually provides server parameters, while the client generates a runtime config based on local ports and routing options. Editing an exported copy does not automatically change the running core; editing a temporary runtime file may be undone the next time you switch servers. First identify which layer you are editing, then decide whether to save through the UI or load a custom config.

While learning, keep two clear baselines: an untouched copy of the complete local config and a second copy with only the fields from the current section added. Note the config source and listening port before running it, then compare the results with what you expected. This helps you tell whether a new field changed request behavior or the client is still loading an older file. Testing one field at a time is easier to reproduce than importing a large set of rules at once.

Inbound Configuration

Listen Address, Port, and Protocol

An inbound determines how local apps connect to the core. listen sets the listening address, port sets the port, and protocol tells the core how to interpret incoming requests. All three must match the proxy address entered in the app. If the app uses the wrong proxy type, the core cannot read the destination as expected, even if the connection reaches the same port.

For use only on the current device, the example explicitly listens on the IPv4 loopback address. If an app uses the local hostname, the system may resolve it to the IPv6 loopback address first. An inbound listening only on IPv4 may not receive that request. For troubleshooting, enter the literal address from the config to make both sides match exactly. Do not expose the listener to your entire LAN just to work around a loopback address mismatch.

{
  "inbounds": [
    {
      "tag": "app-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": { "auth": "noauth", "udp": false }
    },
    {
      "tag": "app-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

Replace the inbound array in the minimal file with this snippet. It assigns a separate port to each type of inbound, making it easier to identify which one an app is using. In the app, point the HTTP proxy setting to the HTTP inbound; for a SOCKS5 test, switch to its port. Some clients can create a mixed listener, but this config does not enable one. Do not apply the setup for a mixed inbound to two separate listeners.

Do not confuse the proxy port with the destination port. The proxy port is the local port the app uses to connect to the core; the destination port comes from the app's request and points to the service it wants to reach. When browsing, an app may use the local HTTP inbound to establish a tunnel to a destination HTTPS service. The destination can keep its usual web port; there is no need to change the local proxy port. “HTTP inbound” describes the proxy handshake, not a restriction to plaintext web traffic at the destination.

Protocol Support and Local Testing

The example disables SOCKS UDP support so you can start by testing common TCP requests. Enabling this option does not send all UDP traffic on the system through the core. The app must send requests in a supported way, and the selected outbound must also handle that traffic. If web pages work but other features have unstable connections, first check which network protocol those features actually use instead of calling it a port failure.

Keep unauthenticated inbounds on the loopback address. Even when limited to the local device, other local programs that can connect to the port may send requests to it. On shared devices or in container environments, identify which processes need access and whether the app and core share the same network environment. A container's loopback address usually points to that container, not to the host's loopback address.

If the listener fails to start, check whether another instance or config is using the same address and port. After changing the port, update any address already entered in browser proxy settings, system proxy settings, and terminal settings. Changing only the core leaves apps pointing at the old listener. See How to Fix a Local Port Conflict for steps to find and resolve port conflicts.

For testing, disable other proxy sources in the test app and leave just one clearly defined inbound. Check whether the core loads successfully, then test a known reachable destination again. Next, try the same address in another app rather than immediately switching outbounds. This separates an app-specific proxy setting from a local listener problem. If only one inbound works, check both ports separately; success on one does not prove the other works.

Inbounds may also include options for identifying destinations. These can provide extra clues for routing supported traffic, but they cannot guarantee recovery of the original domain for every connection. First test how rules match when the app preserves the domain, then decide whether additional identification is actually needed. Identically named options do not necessarily behave the same by default, especially when the client generates the inbound automatically.

Outbound Configuration

Direct and Block Outbounds

An outbound determines what happens after a request leaves the core. It can connect directly to the destination, forward traffic using a remote protocol, or actively reject it. Outbound entries do not take turns handling requests just because they appear in the list. Routing sends a request to a specific outbound; if no rule matches, the first outbound in the list usually handles it. Changing the order can change where all unmatched traffic goes.

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

Replace the outbound array in the minimal config with this snippet. The direct outbound remains first. No rule refers to the block outbound yet, so it will not reject any requests. The next section adds an explicit block rule for a test domain. This order makes the default behavior predictable and helps distinguish a rule match from an unreachable destination when troubleshooting.

Direct means the device running the core connects to the destination; it does not mean the app bypasses the local core. You can compare two tests: let the app connect directly, then send it through the local inbound and direct outbound. If the results differ, first compare how the destination is represented and resolved after it enters the core. If both fail, investigate the device's network and the destination service too, rather than immediately suspecting a remote node.

A block outbound expresses what a rule should do; it is not a check of remote server health. An app may show a rejected connection as a disconnect or simply as a failed request. Do not rely on a single error message in the UI to determine whether a rule matched. One way to test is to temporarily change the rule for a controlled test destination, compare the results, and check the core logs for the inbound and outbound tags.

Remote Server and Transport Parameters

A remote outbound generally depends on two sets of settings. The first is the protocol configuration, such as the server address, port, and authentication details provided by the service. The second describes the transport and security that carry those requests, such as the transport type, path, or expected server name. Getting the first set right does not mean the second is correct. If the remote connection establishes at a lower level but still cannot access destinations, compare each field against the complete config from the service.

The contents of settings depend on the protocol; do not copy the structure from a different protocol. streamSettings describes the transport and related security settings used by an outbound; it is not the same as the system proxy settings. When a subscription generates an outbound, check in the client UI whether these fields are already populated. Do not replace certificate-related options in bulk just to clear an error; that can hide the real issue with a name or time setting.

The local inbound address and the remote server address point in opposite directions. Copying the remote server's port into the local proxy port does not make the core connect to the server. Likewise, entering the local loopback address in a remote outbound does not point to a real service. When entering a parameter, first identify which process reads it, then confirm what is on the other end of the connection. The domain provided by the service is not necessarily the domain of the destination site.

If you want to keep a direct outbound for comparison, give any manually added remote outbound a clear tag and reference it in just one narrowly scoped test rule. First check that requests not matching the rule still follow the original path. If you later replace the remote outbound, keep its tag or update the references too. When checking the impact of one change, do not also move the default outbound.

When reporting an outbound issue, you usually need only the protocol, transport type, error stage, and a redacted outline of the fields. Never include real authentication details in screenshots or publicly shared config files. Describing the local inbound separately from the remote outbound also helps others know where to check logs. If you need to choose one server from several that work, see V2Ray Server Nodes Compared: Latency, Multipliers, and Protocols.

Routing Rules

Choose an Outbound by Rule Order

Routing handles requests that have already entered the core. The system proxy tells apps that follow the setting where to send requests; routing decides where those requests go next. They are not interchangeable. Changing routing mode alone will not make a terminal process that ignores the system proxy connect automatically. For how GUI modes and switches work together, see System Proxy vs. Routing Mode.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["app-socks"],
        "domain": ["full:example.com"],
        "outboundTag": "reject"
      },
      {
        "type": "field",
        "inboundTag": ["app-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}

Add this to an example with the corresponding inbound and two outbounds. The first rule requires both a request from the specified inbound and an exact domain match. It does not block subdomains of that domain. The second rule covers the remaining traffic from that inbound. Requests from other inbounds that do not match still use the default outbound. To test the first rule, the app must pass the domain to the SOCKS inbound; if it resolves the domain to an address first, the current condition cannot match the original domain.

Rules are checked in array order, and the first match determines where a request goes. If you move the broad second rule ahead of the first, the first will never get a chance to match, even if it is correct. For real configs, put exceptions first, broader categories next, and a catch-all last. When conditions from different categories appear in the same rule, treat them as conditions that must all be met, not as independent alternatives.

A domain condition array can contain multiple candidate values. Exact matching works well for testing a single host; use the domain: prefix to match a domain and its subdomains. Do not put a full web address in a domain condition. The path, query parameters, and fragment in a URL are not part of the hostname. If a web page loads resources from other domains, check those connections separately; the page's main domain does not tell you which rule every resource will match.

Domain Policies and IP Rules

When an app passes a domain to the core, AsIs does not resolve it to an address just to match an IP condition in routing. This does not mean the whole request is prevented from being resolved; a direct outbound may still need to resolve the domain. With IPIfNonMatch, the core can resolve the domain for IP rules if the original destination does not match. A catch-all rule that always matches at the end may prevent this fallback matching from taking place.

IPOnDemand triggers resolution as needed when evaluating rules that require an address. Before choosing this policy, identify which rules actually depend on the lookup result. A domain may resolve to multiple addresses, and results can change with the network. An IP-based rule is not a rule based on website identity; different domains sharing an address may receive the same treatment. If the app has already passed an address to the core, first check whether any domain information is still available for matching.

Before using geolocation lists, confirm that the current core can read the required data files and that the referenced categories exist. If you copy only the rules without the data resources originally supplied by the client, the core may fail at startup. First prove the routing logic with a rule that needs no external categories, then add the lists back. This separates field usage from data resource issues.

For each change, test at least one destination that should match and one that should not, and note which inbound the app actually uses. Establish a new connection after changing the config so an existing connection does not continue using the old rules. If the difference appears only in one browser, check whether it resolves domains independently or uses its own proxy rules. Correct rule order alone does not confirm that the input conditions are right.

DNS Configuration

First Identify Where Resolution Happens

Sometimes an app resolves a destination itself and passes an address to the proxy. In other cases, it passes the domain to the local inbound. The core may also resolve domains for routing decisions or direct outbounds. If a remote protocol can forward domains, the remote side may resolve the destination as part of the connection. The top-level dns config manages the core's built-in resolver; it does not automatically take over queries already made or completed at another layer.

The example below uses the local system resolver as a fallback and adds a static mapping for testing. The test name uses a reserved domain. It maps to the local device, making it suitable for a controlled test service running on that same device. This mapping applies only to queries handled by the core's built-in resolver. Start the test service yourself and make sure it listens on the expected port; a connection refusal does not by itself indicate a DNS configuration problem.

{
  "dns": {
    "hosts": { "v2ray-test.invalid": "127.0.0.1" },
    "servers": ["localhost"]
  },
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": { "domainStrategy": "UseIP" }
    }
  ]
}

Adding this to the minimal config replaces the outbound array. UseIP on the direct outbound makes it use the core's built-in resolver for domain destinations and connect by address. If you already have a block outbound from the routing section, keep that entry or remove any references that no longer apply. To test the static mapping, pass the domain—not a pre-resolved address—to the SOCKS inbound.

If the app reports that a domain cannot be found before it connects to the core, first check whether its SOCKS settings allow hostnames to be passed to the proxy. A resolution error in the app is not the same as one in the core logs. A standalone system lookup tool will not use this static mapping just because the core is running. If two query paths give different results, first explain how the paths differ instead of immediately changing system settings.

Address Families, Upstreams, and Caching

When choosing IPv4-only or IPv6-only lookups, distinguish the records returned from the device's actual connectivity. Getting an IPv6 address does not mean the device has a working IPv6 route. Forcing IPv4-only lookups can also leave a destination that publishes only IPv6 addresses without a usable result. Start with the default behavior, then compare it with a single address family. Do not leave a temporary troubleshooting restriction in your everyday config without documenting it.

When changing upstream resolvers, change just one at a time. The resolver itself must also be reachable from the current network. If the upstream is identified by a domain, find out how the core resolves the upstream's own address. For encrypted DNS, use an address format supported by the current core. Copying the syntax from a different core without checking its meaning can send traffic or DNS queries somewhere unexpected.

A failed query does not always cause an immediate attempt to the next upstream in the list. Domain-specific rules, failure fallbacks, and address filters can affect the final choice. Start with one upstream and one destination; after it works, add restrictions one at a time. This helps distinguish an unreachable upstream from a result that was filtered out. DNS timeouts can also consume the app's connection wait time, making the visible error look like a destination connection timeout.

After a config change, an old result may still be cached by the app, the system, or the core. Close the existing test connection, reload the config, and compare a new request. If just one app still gets the old address, check that app's cache and custom DNS settings; there is no need to reset the whole device's network first. Recording the test time and DNS path makes changes easier to explain than recording an address alone.

Document why a static entry exists and when it should be removed. A local mapping used for testing does not belong in a production config for everyday use. After removing test entries, check routing and the direct outbound with a normally resolved destination. A DNS config working in a local example does not prove that traffic resolved remotely will get the same result.

Connection Policies

What Levels and Timeouts Control

Policies describe how connections wait and close, and whether specific statistics are collected. They do not route a domain to an outbound or replace an app's own retries and timeouts. First find the inbound and outbound used by the request, then check the connection policy. Increasing several timeouts first can turn an easy-to-reproduce issue into a long, difficult-to-observe hang.

Level policies go in levels, with the level number as a string key in the object. The example configures level zero to examine connections that use it. Some protocols or user configurations allow a different level; the existence of a policy does not mean every protocol or connection uses it. First check how the relevant protocol selects a level, then decide whether to change level zero or define a separate set of values for a specific use.

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 300,
        "uplinkOnly": 2,
        "downlinkOnly": 5
      }
    }
  }
}

These values are in seconds and are meant to illustrate how to investigate, not to serve as universal recommendations. handshake limits the handshake wait for applicable connections; it does not time the entire page load. connIdle concerns waiting while no data is being transferred. A request that remains slow while data is still flowing differs from a connection that has been completely idle for a long time. Do not treat them as the same timeout issue.

uplinkOnly and downlinkOnly control how long to wait when only one direction continues transferring data. One side finishing its sends does not mean the other side has finished sending its response. Ending a one-way wait too early can leave the final part of a response missing even if it starts normally. When investigating this, note which direction finished first and whether the issue occurs only with a specific app or destination.

Change One Policy Setting at a Time

Reproduce the issue with the original config first, then choose the setting most relevant to what you observe. If a connection repeatedly fails before it is established, note the time from starting it to the error. If it drops after sitting idle for a while, note when data was last sent or received before the disconnect. Change one field and test with a new connection. If there is no improvement, restore the original value instead of increasing every timeout.

Browsers, terminals, remote services, and intermediate devices can all close connections. If an app has already stopped waiting, a longer idle timeout in the core cannot recover that request. If different connections drop at similar times, compare them with a local direct-connection baseline. If it happens only through one remote outbound, check the remote service settings and network path instead of attributing the timing to a local policy.

Some policy switches only determine whether counters are collected for specific objects. Whether statistics are enabled, a connection has an identifiable user, and the UI can read the data are separate concerns. Traffic totals shown in a GUI do not necessarily come from the same counters as the core. You do not need to enable all statistics and keep detailed logs long-term just to investigate one connection failure.

When choosing settings for everyday use, balance closing idle connections with keeping sessions that send or receive data occasionally. A very short idle timeout can make some apps reconnect frequently; a very long one may keep unused connections open. During a long period without a response, first determine whether the app is waiting for a result rather than mistaking an active transfer for an idle connection. Retest with the app that had the issue; one short request cannot prove a long-lived session is fixed.

Note the reason for each change, the test conditions, and the original values. After upgrading the core or changing clients, check again that the level is taking effect; comparing config text alone is not enough. If a policy change seems to make no difference, first confirm the loaded config source and the actual level used by the connection. Tests are comparable only when these conditions are clear.

Client Configuration and Core Differences

Choose the Right Place to Make Changes

For desktop, start with v2rayN, using the installer for Windows, macOS, or Linux. On Android, consider v2rayNG, which uses the Xray core. If you need the V2Fly core, choose v2flyNG. Find all three clients on the download page. For a first setup, simply choose the installer for your operating system and device architecture; there is no need to write a core config by hand.

ClientPlatformCheck First
v2rayNWindows、macOS、LinuxRunning core, local listener, system proxy
v2rayNGAndroidConnection permissions, app scope, Xray fields
v2flyNGAndroidConnection permissions, app scope, V2Fly fields

GUI clients usually store server entries, subscription URLs, local ports, and routing preferences as separate types of data. When you select a server and start the client, it generates the config the core needs from those settings. Importing a set of servers is not the same as importing a complete core config, and backing up the server list does not save local routing rules. Before making a change, decide whether you want to change server settings, the connection entry point, or the entire runtime config.

On desktop, changing how apps connect usually starts with the local listener and system proxy settings. Setting the system proxy to automatic configuration provides an entry point for apps that follow system settings; it does not route all traffic. Proxy settings differ across desktop operating systems, and an app may use its own proxy settings instead. Before testing, note whether the app reads the system settings or uses a manually entered address.

On Android, the client often uses the system's connection mechanism to route app traffic. Whether traffic can start flowing depends on permissions and which apps are included. Do not use the desktop test method of manually connecting software to a loopback port as a mobile setup guide. If just one app always works or always fails, first check whether it is included in the current client's scope, then compare the core's routing results.

Keep Client-Generated Sections When Migrating

Core families share many basic fields, but protocol options, transport names, and extended behavior are not guaranteed to match. Before importing, confirm which core the new environment actually uses; do not infer it from the client name or file extension alone. Start with a config generated by the target client, then migrate only the fields you need. Keep the original sections that the client manages for connectivity, interfaces, and other internal settings instead of blindly copying them from another device.

The snippet below only shows how to set a more practical log level for everyday use. If a log object already exists, merge in the level field without removing other settings. When the UI generates the runtime config, use its logging options where possible; set the value in the relevant file only when starting with a custom config. This also makes it easier to tell where the setting comes from after a restart or subscription update.

{
  "log": {
    "loglevel": "warning"
  }
}

Before switching devices, list the behaviors you need to keep, such as per-app routing, a local listener, or destinations that should use a specific outbound. First verify a basic connection in the new environment, then restore routing and DNS settings one at a time. If the server list changes after a subscription update, see Subscription Groups and Server Filtering to check the source. This helps avoid mistaking a same-named entry from another group for the current server.

Exported configs may contain subscription URLs and authentication parameters; keep them in your own working environment. If you need help from someone else, create a separate note containing only the relevant fields, then reproduce the public issue with a local direct-connection example. This protects private connection details and narrows down what they need to check. When reporting an issue, include the client name, operating system, and core in use; that is more useful than simply saying “import failed.”

After migrating, verify the behavior at least once after restarting the client. A setting that works only in the current session may not have been saved to the source used to generate the next config. If the behavior changes after restarting, check the active server entry, subscription group, and selected custom file. Confirm the selected config has not changed before investigating whether different cores handle the same field differently.

Config Validation and Troubleshooting

Narrow Down the Issue from Startup

First check whether the core started successfully. File parsing errors often appear as soon as the config loads, while a listener conflict occurs when the core tries to open a local inbound. Both can make the client seem completely unusable, but they have different fixes. Read the first clear error from this startup, then check the later messages. A chain of errors caused by one failed initialization is usually not a set of separate problems to fix one by one.

For a syntax error, check brackets, commas, and quotes starting at the reported location and working backward. If the error points to the next line, the missing symbol may be on the line before it. If the config parses but still will not load, check field types, protocol names, references, and data files. Valid JSON proves only that the text structure is readable; it does not prove the current core recognizes every field or that an outbound can connect.

Once the core is running, check whether the app can connect to it. Test with an app configured to use one specified proxy type and address; do not enable both the system proxy and the app's own proxy at the same time. If the app reports a connection refusal, first check the local address and listening port. If the request reaches the core but cannot reach its destination, check the matching outbound and DNS results. If the browser works but the terminal does not, see How to Troubleshoot Browser and Terminal Proxy Settings Separately to identify where each gets its settings.

Compare Logs and Roll Back in Order

If needed, temporarily add diagnostic detail with the snippet below. It changes only the log level; it does not add a listener or change the default outbound. Restore the original level after reproducing the issue; logs may reveal destinations or network details. Limit log review to the time window of one test, and do not rely on exact message text because clients and cores may format it differently.

{
  "log": {
    "loglevel": "info"
  }
}

If a request reaches the core but uses an unexpected outbound, check rule order, inbound tag, target format, and outbound tag in that order. Testing an address alone does not prove a domain rule works. If the selected outbound is correct but the connection times out, use a direct-connection baseline to check the local path, then inspect the transport, DNS, and remote settings used by that outbound. Change only one variable per test; do not switch both the inbound and outbound at once.

If a domain fails but a direct address works, test DNS separately. Record who resolves the domain and whether the request still contains the domain when it reaches the core. For services that depend on the server name, connecting directly by address may cause a certificate name error; that does not mean the network is unreachable. If failures happen only after idle periods, test idle time separately before changing connection policies.

To roll back, stop loading the problematic config, restore a known-good copy, and update the proxy address used by the app. Rolling back only the core while leaving the new system proxy port in place can leave the problem unresolved. Once the original path works again, reapply changes one section at a time in this order: inbounds, outbounds, routing, DNS, and policies. The first section that brings the issue back is where to focus the next round of troubleshooting.

For recurring issues, keep a short record of the triggering action, inbound, comparison path, changed fields, results, and rollback steps. Reproduce the issue before drawing conclusions. One successful connection does not prove every app connects the same way, and one failed connection does not invalidate the entire config. Keep the smallest reproducible case handy so you can retest after client updates or subscription changes.