Configuration Reference / JSON

V2Ray Configuration File:JSON Field Reference

Trace a connection through the config: which inbound receives it, which outbound routing selects, and what handles DNS resolution and timeouts.

For your first install or subscription import, follow the quick start guide to get a connection working. Use this page to look up fields when editing a config, with local listener and direct-connection examples to distinguish core behavior from client traffic handling.

JSON Structure Overview

Know the difference between root objects, arrays, and protocol settings

A typical V2Ray-compatible JSON config has an object at its root. inbounds and outbounds are arrays because a config can define multiple entry points and exits. routing, dns, policy, and log are usually objects describing traffic selection, name resolution, connection policies, and logging. Check the type of each nested value as well: routing.rules is an array, while policy.levels is an object keyed by level number. Indentation helps readability; it doesn't change how fields are nested.

When you see settings, first check the protocol at the same level. This field appears in many inbounds and outbounds, but there is no universal set of options. SOCKS inbound authentication options don't apply to an HTTP inbound, and an outbound destination can't be replaced with an inbound listen address. When troubleshooting, note the full field path—for example, “the first inbound's listening port” or “the second routing rule's target tag.” That's more useful than remembering a field name alone.

A standalone local baseline that starts on its own

Complete example · Loopback HTTP inbound with a direct outbound
{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "http-local",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ]
}

This is a complete, standalone baseline that a core supporting these fields can load. It listens only on the local machine at 127.0.0.1:10809; apps with proxy settings can use it as an explicit HTTP proxy. There is one outbound, and without additional routing, ordinary requests passed to the core go out directly by default. This baseline contains no remote server details, doesn't configure the system proxy, and doesn't create a virtual network interface. If a desktop client already uses this port, choose an unused port and update the test app to match.

Check the baseline in two steps. If startup completes without a config error, the core accepted the config and attempted to listen—but you still need to send a request to a specific target to confirm that the app, inbound, and outbound all take part in the connection. First access the target directly from the same app, then access it through the explicitly configured proxy. If the direct request already fails, the baseline may fail too; that doesn't prove the inbound is misconfigured. Don't change the system-wide proxy during testing, or requests from other apps may affect the results.

How to merge standalone files and section snippets

Config blocks below labeled “Replace field” or “Add to root object” are partial examples. The outer braces show where the content belongs; they don't mean you should start another file or paste a second root object at the end. If the root already has a field with the same name, replace that field with the example or merge its data as needed. Recheck rule order when merging routing and check ports when merging inbounds. A clean-looking editor doesn't guarantee the merged config meets runtime requirements.

Strict JSON avoids ambiguity across different import paths. Enclose keys and strings in straight double quotes, leave numeric ports unquoted, omit trailing commas from objects and arrays, and don't add comments to the code. Duplicate keys are especially hard to spot: some parsers reject them, while others keep the later value, making earlier settings appear to have no effect. Save as UTF-8 and keep the runtime copy separate from your working draft. For client-generated configs, make changes through the client's supported settings whenever possible so they aren't overwritten the next time you switch configs.

inbounds

Match the listen address, port, and protocol

An inbound defines where the core accepts connections and which protocol it uses to interpret the app's data. listen is an address on the device running the core, not the remote server's address. port is the local port the app should connect to, not the port on the remote service. A loopback address keeps local testing separate from LAN access. Even if both addresses point to the same computer, an inbound listening on loopback won't accept requests sent to the machine's network-interface address.

The proxy type selected in the app matters too. An HTTP proxy setting needs an HTTP inbound; a SOCKS proxy setting needs a SOCKS inbound. With the right address and port but the wrong protocol, the socket may connect successfully while the proxy negotiation fails. Also check whether the app defaults to localhost: if it tries the IPv6 loopback address first but the config listens only on IPv4, temporarily set the app's address to 127.0.0.1 to rule out an address-family mismatch.

Give each inbound its own tag

Replace field · Keep HTTP and add a SOCKS inbound
{
  "inbounds": [
    {
      "tag": "socks-local",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    },
    {
      "tag": "http-local",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

This example puts the two protocols on separate ports for easier comparison. tag is an internal config label; apps still connect using an address and port. Keep tags unique and stable. To test requests from different apps separately, give them different inbounds, then use inboundTag in routing.rules to distinguish them rather than inferring routes from app names. Inbound and outbound tags don't have to match. Using distinct names makes it easy to tell in logs whether a connection is entering or leaving.

The SOCKS inbound in this example requires no authentication and listens only on the local machine. SOCKS UDP forwarding is disabled, making this suitable for first testing TCP traffic such as ordinary web requests. If the test app mainly uses UDP, a successful SOCKS TCP test doesn't prove it will work; also check whether the app supports the relevant proxy forwarding, whether the inbound allows it, and whether the outbound can carry that traffic. Don't widen the listen address just to see a connection—local testing doesn't require other devices to access the proxy.

Use the failure stage to diagnose inbound issues

If the core reports a bind failure at startup, first check that the listen address belongs to the local machine, then see whether an old instance, a client's built-in inbound, or another program is using the port. When choosing a new port, update more than the config file: the browser's manual proxy, system proxy settings, and test commands may still point to the old port. If the config and test settings don't match, the request might reach a different proxy that's still running, making the change look ineffective.

If the port accepts connections but the expected inbound tag doesn't appear in the logs, check whether the app is using its own proxy settings, has a destination exception, or reused an existing connection. Once the inbound tag appears, move on to the outbound and domain matching. Also check whether the inbound received a domain name or an address the app resolved in advance: if the app resolved it first, domain rules may not have a name to match. The issue may not be the listen protocol. Preserve the test conditions, note what kind of destination the app actually sent, and then investigate the later rules.

outbounds

The first entry is the default outbound; tags are for routing

After an inbound receives a request, the core must decide how to connect to its destination. Each entry's protocol in outbounds defines what it actually does; tag is just an identifier for routing. Naming a tag direct doesn't turn an arbitrary protocol into a direct connection, and naming one blocked doesn't automatically block traffic. For ordinary requests that match no routing rule, the first outbound in the array is the default. Listing two entries side by side doesn't mean the core will try them in parallel or switch automatically if one fails.

A direct outbound by default works well for this page's local experiments because it doesn't depend on a server. It isn't necessarily the right default for every real-world setup. First decide whether destinations not covered by your rules should be allowed to connect directly, then choose the default outbound. To check whether your rules cover all intended cases, use a deny outbound as the default in a separate test config and explicitly allow known destinations. This helps expose unmatched traffic; don't apply it directly to a config serving multiple apps.

Two minimal behaviors: direct and deny

Replace field · Direct by default, with a deny outbound for routing
{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "blocked",
      "protocol": "blackhole",
      "settings": {
        "response": {
          "type": "none"
        }
      }
    }
  ]
}

freedom connects directly to the destination. The local network and name-resolution behavior depend on the runtime environment and outbound settings. It doesn't send a request to a remote proxy just because the request came through a proxy inbound. blackhole doesn't connect to the destination. This example sets the response type to none, so the app may see a closed connection or a generic proxy error—not a page explaining why the request was blocked. To distinguish an intentional denial from a destination failure, check the selected outbound and the destination service's logs, not just the app's error message.

The second entry in this example won't handle ordinary requests until a routing rule selects it. Keep the array order and add a narrowly scoped rule to test the deny behavior; if the test fails, check whether an earlier rule matched first. If you rename an outbound, update every rule that references its old tag and check capitalization. An unresolved outbound tag isn't a usable fallback route, and a successfully loaded config doesn't guarantee requests will fall back to the first entry.

Check remote connection settings against the server parameters

When configuring a remote outbound, distinguish the proxy protocol, the transport carrying the connection, and the transport's security layer. They're related, but they aren't interchangeable. The same proxy protocol can use different transports, and matching addresses and ports don't prove the two sides are configured alike. After importing a share link, check in the client that the converted protocol, transport, and security settings match the provider's instructions. Different core families may not support the same fields or values, so don't copy a few settings from another example and paste them in.

When changing remote settings, keep the known-working local inbound, test app, and destination fixed; change one condition at a time. If the inbound appears in the logs but the remote connection times out, check separately whether the remote address resolves, whether its port accepts connections, and whether the failure occurs during connection setup or the handshake. If the local direct baseline can reach the test destination, that only confirms the local direct path works; it doesn't validate the remote server settings. For protocol details, see Proxy Protocol Comparison, then return to the actual config to find the difference.

routing rules

Put specific rules before general ones

routing.rules are checked in array order. For rules using fields like those shown below, the first matching rule selects its outbound and later rules aren't checked, even if they're more specific. For example, if a direct rule covering a network range comes before a deny rule for one device in that range, the latter usually won't run. Put narrower exceptions before broader rules. When debugging, start at the top of the list and look for the first rule that could match, rather than focusing only on the one you edited last.

If a field-based rule includes both inboundTag and ip, this example requires both the inbound and destination address to match. A list within a single field can contain multiple candidate values. If you mean “from this inbound OR to an address in this range,” write two separate rules that select the same outbound. Confusing these patterns often means one sample destination happens to match, but another app or address goes to the default outbound instead.

Test rule order and scope with local requests

Add to root object · Test with the two-inbound and two-outbound snippets
{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["socks-local"],
        "ip": ["127.0.0.1/32"],
        "outboundTag": "blocked"
      },
      {
        "type": "field",
        "ip": ["127.0.0.0/8"],
        "outboundTag": "direct"
      }
    ]
  }
}

Set up a local HTTP test service that already works with a direct connection. Use 127.0.0.1 and the service's own port as the destination, not the proxy's listening port. A connection through the SOCKS inbound matches the first rule and goes to the deny outbound. The same destination through the HTTP inbound doesn't match the first rule, so it continues to the second. Swap the rules and open a new connection to see the broader address rule take precedence over the inbound-specific rule. The literal address keeps DNS differences out of this routing test.

In a production config, distinguish three things: a matching rule, the default outbound used when no rule matches, and a failure in the selected outbound. Without an explicit catch-all rule, the first outbound still matters. Add a broad catch-all and later rules may become unreachable. If the logs show the expected outbound but the connection still fails, investigate that outbound and the destination service instead of repeatedly changing rule order. When adding an exception to existing rules, test a separate destination that should remain unaffected so you don't only test the new case.

Domain rules and address rules use different inputs

Use full:example.test for an exact match and domain:example.test to include the domain and its subdomains. Clear prefixes are easier to review than relying on substring matching. Entries such as geosite:cn reference categories in domain data. The core must be able to find the relevant data, and the actual loaded data determines what matches. This isn't geolocation and doesn't guarantee coverage of every domain associated with a service. Check the destination in the actual request to see whether a domain list matched.

AsIs doesn't resolve a domain to an address just for routing. IPIfNonMatch can try matching the resolved address if the first pass finds no match. Before choosing the latter, consider lookup delays, how the resolved address relates to the eventual connection target, and whether a catch-all rule already matches during the first pass. Neither strategy can recover a domain name from an arbitrary IP address submitted by the app. To test a domain rule, make sure the app passes the destination name to the inbound, then check whether it reaches the expected matching branch.

dns resolution

First find out which component is making the query

The root-level dns object controls the core's name-resolution behavior. It isn't the operating system's DNS settings, and it doesn't take over every query an app makes. An app may resolve a domain first and pass the resulting address to the proxy, or preserve the domain in the proxy request; some apps also have their own DNS settings. Before deciding a setting is working, check the destination format in the current request and whether the core's routing or outbound uses the built-in resolver. Seeing a domain in the browser doesn't mean that same string reached the core.

Keep DNS resolution for routing separate from resolution for the outbound. The former checks whether a destination matches an address rule; the latter resolves a destination for the eventual connection. A routing lookup doesn't mean every protocol, outbound, and app uses the same result. Different paths may use separate caches or choose different address families. Don't treat “the domain resolves” and “the current connection uses that address” as the same thing. If needed, record what you observe for both the destination and the outbound.

Use a static mapping to test the built-in resolution path

Paired change · Add dns and replace the baseline outbounds
{
  "dns": {
    "hosts": {
      "example.test": "127.0.0.1"
    },
    "servers": ["localhost"]
  },
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "UseIP"
      }
    }
  ]
}

Add this dns object to the single-inbound baseline and replace the existing outbound. The direct outbound uses UseIP, so the built-in resolver can look up the test destination while it remains a domain name. hosts maps the test name to the loopback address without changing the system's hosts file. In servers, localhost means to use the local resolution capability; it doesn't imply that a DNS server is listening on the loopback address. The test name uses a reserved suffix. Access a running local test service through the proxy; this isn't a public website.

Test this example against the original baseline, not a config from the previous section that still references blocked, or you'll remove an outbound that a rule needs. If the app bypasses the proxy for the test name or tries to resolve it with its own resolver first, the static mapping won't pass through the core. Conversely, changing back to the direct outbound's default domain handling may cause the system to try to resolve the same name. Compare two configs that differ only in outbound resolution strategy, opening a new connection for each test, to distinguish the built-in mapping from system resolution.

Upstream groups, address families, and caching

If different domains need different upstream resolvers, check whether your core supports options on servers entries, such as using address to specify a resolver endpoint and domains to define its matching scope. Adding a dedicated upstream doesn't necessarily mean other servers won't be used for everything else; check the core's rules for candidate order, failure fallback, and result filtering. With an HTTPS-based resolver, also check how its endpoint is resolved and reached. If the endpoint's domain can only be resolved by querying that same endpoint, there's no reliable way to bootstrap the connection.

If a literal address works but a domain doesn't, first test the layer responsible for the query, then check which address families its result contains. IPv4-only or IPv6-only policies can leave some destinations without a suitable result. They're useful for narrowing down an issue, but aren't a general fix for every network problem. After changing settings, account for existing app and system DNS caches and open connections; they don't all refresh at the same time. Close old connections and test a clearly identified destination, then check which layer still returns the old address before clearing the relevant cache.

policy connection policies

Level policies control connection behavior, not outbound selection

policy describes how the core handles connection lifetimes, buffering, statistics, and related behavior; it doesn't route domains to different outbounds. policy.levels is an object whose keys are level numbers written as strings, such as "0". The level used by a connection depends on the protocol and the user level configured on the inbound. Defining a new level doesn't automatically move requests to it. Before checking its settings, verify how the current protocol selects a level, and test the default and explicitly assigned levels separately.

It's easy to use policies to mask earlier config errors. Extending a timeout won't fix an unreachable inbound port, mismatched remote transport settings, or DNS queries taking an unexpected path; it may only delay when the app sees the error. First confirm the path with a minimal config, then adjust policies to address a specific observed behavior. For example, a connection that drops only after all activity stops isn't the same as one that's slow while data is still flowing, and the same timeout setting shouldn't be used to explain both.

Understand handshake, idle, and one-way shutdown separately

Add to root object · Demonstrate timeouts at level 0, in seconds
{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 180,
        "uplinkOnly": 4,
        "downlinkOnly": 12
      }
    }
  }
}

handshake limits how long applicable protocols wait for the initial handshake. It isn't a universal connection timeout for every network operation and doesn't override timeouts in the remote program. connIdle concerns how long a connection remains idle; it isn't a maximum lifetime measured from connection setup. The values in this example only distinguish the different timers and don't represent defaults for any client. If the app has a shorter timeout, it's likely to end the request first.

uplinkOnly applies when only the upload direction remains: it sets how long the upload can continue after the download has ended. downlinkOnly applies when only the download remains. Neither setting limits upload or download speed. Ending one direction immediately can cut off a response that hasn't finished; waiting too long can keep a useless connection open and consume resources. To test these settings, choose an app where you can clearly observe when reading and writing stop. A successful short request doesn't verify long-lived connections or one-way shutdown behavior.

Distinguish user levels, system statistics, and client UI

policy.system controls system-level core behavior. Some implementations support enabling inbound or outbound counters here; user counters belong to the settings for the corresponding level. Whether counters are generated, whether the client can read them, and whether they appear in the UI are three separate requirements. Check that the relevant statistics module and read access are enabled. Adding policy fields doesn't guarantee that numbers will appear in the UI, and you shouldn't expose a management interface to other devices just to inspect counters.

When tuning a policy, keep a control case: use the same app, inbound, outbound, and destination, changing only the level setting being tested, and make a fresh connection. Record whether the error occurs on the initial request, after an idle period, or after part of the response arrives; that helps identify the relevant timer. If only one app has a problem while others work through the same inbound and outbound, check that app's retry and connection-pool settings too. Keep a change only after observing a consistent difference, and restore other test settings to the baseline so multiple timeout changes don't make the next result impossible to explain.

Client Configuration and Scope

Distinguish subscriptions, individual share links, and core config files

For desktop, start with v2rayN. On Android, choose v2rayNG or v2flyNG based on the core you need; find installation options on the downloads page. Clients store connection records in a format different from the core's runtime config. A subscription URL usually retrieves a set of connection records; an individual share link describes one connection; a complete core config can define inbounds, outbounds, DNS, and routing together. Importing one type successfully doesn't mean another type can be pasted into the same place.

If you already have a subscription and just want to add a connection, keep using the client's connection management and update options. To change root-level fields covered on this page, first check whether the client exposes the relevant setting or supports importing this type of custom config. If you're unsure which import option to use, read Subscription Import and Share Formats. A client's internal files may contain UI preferences and record indexes; editing them isn't the same as changing the core's JSON. Treating a client data file as a core config often causes startup to fail.

The same config fields don't mean the same traffic handling

Platform Client What to check when validating the config
Windows v2rayN Does the system proxy point to the current inbound? Does the test app follow system proxy settings?
macOS v2rayN Does the active network service have the relevant proxy enabled? Keep the network service fixed when comparing results.
Android v2rayNG / v2flyNG Does the connection authorization and app scope include the test app? Is the import format compatible with the core?
Linux v2rayN Do the desktop proxy settings match the individual process's proxy settings? Does the terminal tool have separate environment settings?

A system proxy usually depends on apps reading and following the system settings; saving JSON doesn't change that by itself. When testing a specific inbound on desktop, start with the app's manual proxy settings rather than enabling every traffic-capture method at once. If an explicitly configured proxy works but the system proxy doesn't, check how the app reads system settings, whether an exception applies, and which port the client configured. Switching to a different outbound protocol usually just adds another variable.

TUN mode receives traffic through a virtual network interface and depends on routing scope, app scope, system permissions, and other conditions. It isn't a SOCKS inbound renamed to TUN, nor a one-click workaround for every app restriction. On Android, also check system authorization and client settings for traffic scope. A single-port test config working on desktop doesn't prove that a mobile device will manage traffic the same way. When moving a config across platforms, reuse protocol-related settings first, then verify separately how each platform sends traffic to the core.

Check which config and core are actually loaded

A client's GUI settings often generate a runtime config at startup or when you switch connections. Manually editing a temporary file in the runtime directory may be undone at the next startup. Make lasting changes through a client-supported setting or a supported standalone config file. To confirm a change reached the current instance, choose a clearly different local test port, restart the connection, and have the app explicitly access the new port; compare it with the old one. “Saved” in the UI doesn't prove the core reloaded the file.

Different clients may use cores that interpret the same extension field differently or support different options. When migrating a config, first check compatibility at the root-object and protocol level, then restore optional features one by one. If an error appears only after adding a section, keep the last version that started successfully and note the full path of the failing section. When asking for help, share only the relevant structure and nearby error output, removing subscription URLs, credentials, and unnecessary network details. Reproduction steps are more useful than a full runtime config.

Config Validation and Log Troubleshooting

Check three stages: parsing, listening, and forwarding

If the core exits on startup, first check whether the running core can parse the file. Use the error location to inspect the preceding line for commas, quotes, and brackets, then check field types and whether the file was loaded through the correct import path. Valid syntax only means the object can be read; it doesn't mean every field is valid. Start with the first clear error, fix it, and restart. One misplaced bracket can trigger errors across many later lines, and fixing those resulting errors one by one can damage otherwise correct content.

After parsing succeeds, check the logs for a bind failure or a port conflict, then use a fixed destination to confirm the request enters the intended inbound. The commands below assume an HTTP test service is available locally at 127.0.0.1:8000 and use the baseline from the first section, not an experimental config with a deny rule. The first command bypasses the proxy; the second explicitly uses the HTTP proxy and clears proxy exceptions for that request. On Windows, if the command name conflicts with a shell alias, use curl.exe.

Compare requests · Direct first, then through the local HTTP inbound
curl --noproxy "*" --max-time 5 http://127.0.0.1:8000/
curl --noproxy "" --proxy http://127.0.0.1:10809 --max-time 5 http://127.0.0.1:8000/

Use the same destination and path for both tests, and make sure the proxy port in the second command matches the config. If the first request works but the second can't connect to the proxy, check the listener. If it connects to the proxy but returns an error, check whether an unexpected outbound was selected or the destination refused the connection. Two successful requests only prove this local HTTP path works; they don't prove other destinations, protocols, or system-wide traffic handling work. Add other inbounds, routing, or remote outbounds one at a time, and investigate the input and output at the step where behavior changes.

Narrow down issues by the stage shown in the logs

Read logs alongside a repeatable action. Note the time, close unrelated test windows, send a new request, then check the inbound, destination, outbound, and failure reason from the same period. The default baseline uses warning, so successful forwarding may not produce detailed entries. If you need more information, temporarily increase the log verbosity and use the client's access logs or log viewer. Different cores may phrase messages differently; focus on the connection stage, not on finding an identical error string.

If the logs show the right outbound but the remote handshake fails, check the server's transport and security requirements, as well as the device clock and local trusted certificate setup. If only domain requests fail, revisit the DNS section to see which component is making the query. If connections drop only after sitting idle, compare the behavior with the timers in the connection policy section. For more examples, see v2rayN Logs and Error Troubleshooting. For the basic sequence of choosing a client and diagnosing connection failures, see 10 Common V2Ray Questions for Beginners.

Restore test changes and keep reproducible notes

When testing is complete, restore temporary system or app proxy settings, stop test inbounds you no longer need, and return the log level to its normal setting. Save the final file alongside the previous baseline and note the changed field paths and the destination, inbound, and expected outbound used to test them. If a connection fails next time, rerun the same test and revert the problematic change instead of replacing the whole config. Use this page's contents to return to a section for more context. If you're unsure which layer a term refers to, see the V2Ray Glossary.

Download clients