Getting Started

Getting Started with v2rayN and v2rayNG

First, get one app to send a request through the client; adjust routing rules later. Before you begin, make sure the client is installed and you have a working subscription URL. If you still need to install it, choose a package for your platform in the download center.

Step 01

Import and Refresh a Subscription

A subscription URL provides a set of server configurations. Add it to the client, then refresh the subscription to load the server entries. Copy the full URL from your configuration provider; don't include the page title or any surrounding instructions. The URL may contain access credentials, so paste it only into the client's subscription settings. When sharing screenshots, hide the address bar and subscription URL.

Add a Group in v2rayN

Open the v2rayN main window, select “Subscription Group” at the top, then open “Subscription Group Settings.” Add a record, enter a recognizable name in the remarks field, paste the full subscription URL into the address field, and save. Return to the main window. Seeing the group name only confirms that the record was saved. Select the new group, then choose the option to update the current subscription from the “Subscription Group” menu. If your current network can reach the subscription source directly, choose an update option labeled “no proxy” for the initial fetch. When the update finishes, check the selected group and confirm that server entries appear in the list.

Add a Group in v2rayNG

On the main screen, tap the menu in the upper-left corner and open “Subscription Group Settings,” then tap the plus button in the upper-right corner. Enter a name and subscription URL, make sure updates are enabled for the group, and tap Save. Return to the main screen, open the menu in the upper-right corner, and select “Update subscription.” After the update, switch to the group and check whether entries appear. The save screen and update option are in different places, so update the subscription after leaving the editor instead of tapping the connect button at the bottom.

If the List Is Empty, Check the Update

If the client reports an update failure, first identify whether it couldn't fetch the URL or parse its contents. For a connection timeout, check whether your current network can reach the subscription source. If access is denied, ask your configuration provider whether the URL is still valid. For a parse error, make sure the URL returns subscription data supported by the client, not a login page. If the update completes but the list is still empty, check that you're viewing the right group and whether it has any filters. Continue only when at least one configuration is available to select. See the glossary for the difference between a subscription and an individual server configuration.

Step 02

Choose a Proxy Mode

Once server entries appear, decide how the test app will send requests to the client. The proxy mode determines which requests reach the client; routing rules determine which outbound route they take. These are separate settings: enabling the system proxy doesn't prevent rules from sending traffic directly, and correct routing rules won't affect requests that never reach the client. For the initial setup, keep your existing routing rules and configure just one way to route traffic through the client.

Start with the System Proxy on Desktop

In v2rayN, find the “System Proxy” menu, usually in the context menu when you right-click the tray icon. When you connect in the next step, choose “Auto Configure System Proxy” to point the system proxy to the client's local listening port. For now, just locate the menu; enable it after selecting an active server. Test with a browser that uses the system proxy settings. If the browser has its own proxy configured, check whether it's set to use the system settings—changing v2rayN won't override the browser's internal proxy options.

If your organization or another tool already manages proxy settings, note the existing configuration before making changes. To test a single app, you can also enter the local address and port shown in the client settings in an app that supports manual proxy configuration. Don't use a SOCKS port as an HTTP port. You don't need to enable TUN mode for the initial test. For apps that don't use the system proxy, see the advanced manual for TUN and routing settings.

Start with the Default VPN Mode on Android

In v2rayNG, open “Settings” from the side menu. If your version has a “Running mode” option, choose VPN mode for the initial test, not a mode that only provides a local proxy port. VPN mode uses the system interface to route eligible app requests through the client, so you don't need to enter a proxy address for your Wi-Fi network. If “Per-app proxy” is enabled, check whether the browser you're testing is included or excluded. Keep the default app selection for the first test; narrow it down after verifying the request path. If another app is already using the system VPN, check whether its session can be interrupted before switching to v2rayNG.

Step 03

Connect to a Server

Choose a server from the updated group that your configuration provider has confirmed is available. Note the entry's remarks so you can identify it in the logs. If entries have the same name, check which group they belong to before testing to avoid selecting one from another source. For the first connection, change just one entry. Don't modify the protocol, port, and routing at the same time, or it will be difficult to tell whether an error comes from the original configuration or your changes.

Set the Active Server in v2rayN

In the server list, right-click the entry you want and choose “Set as active server.” If the interface says “Set as active configuration,” it means the same thing. Make sure the active indicator appears on the intended entry. Clicking a row usually only selects it; it doesn't switch the running configuration. Then choose “Auto Configure System Proxy” from the system proxy menu. If you decided to set the proxy manually in the app, leave the system proxy unchanged and make sure the test app uses the local listening address and port currently shown in the client.

If the client reports that the core failed to start, open the message or log panel and check for a port conflict or configuration loading error. For a port conflict, check whether another client instance is running. If you need to change a local port, update any apps where you've entered that port manually. If the configuration fails to load, check the active entry in the list again; repeatedly toggling the system proxy won't fix it. The proxy menu status and the core's running status are separate. Test a request after the error is resolved.

Start a Connection in v2rayNG

Return to the main screen, tap the target entry, and confirm that it is selected. Then tap the connect button at the bottom. The first time you start the VPN, Android will show a connection request. Confirm it after checking that v2rayNG initiated it. Return to the client and wait for the button to show that it's running, then check whether the system shows a VPN status. If the button quickly returns to the stopped state, check the connection logs or system authorization prompt first. A VPN status only means the device has started routing eligible requests; it doesn't confirm that the remote server handled them.

Step 04

Verify the Proxy Is Working

Use the same network, browser, and test destination throughout. Choose a known working URL that should use the proxy under your current routing rules, and note what happens with the proxy off. If you're already connected, temporarily disable proxy routing to establish a baseline, then restore your previous settings. Send a new request each time, avoiding previously opened pages and browser cache where possible. Loading the same page both times doesn't mean the same outbound route was used, and the page doesn't have to fail with the proxy off.

Check Whether the Request Reached the Client

After enabling proxy routing, revisit the destination and open the client logs. Look for connection records from that time. If your log level and configuration record requests, check the destination domain or address, then look for an outbound tag. If the request went direct, check whether a direct-routing rule matched the destination or whether you chose the wrong test URL. If there's no record, first confirm that access logging is enabled; its absence doesn't prove the client never received the request. Check whether the browser uses the system proxy or whether the destination is excluded by v2rayNG's per-app settings.

Find Out Whether the Failure Happened Before or After Proxying

If the browser says the proxy connection was refused, compare the app's proxy settings with the local listening port and make sure the client is still running. If the destination appears in the logs but the remote connection times out, keep the same proxy mode and test destination, switch to a different server confirmed to be available, and send a new request. If the logs show a DNS resolution error, determine whether it was the server address or the destination domain that failed to resolve. These happen at different stages, so there's no need to change both system DNS and client DNS. The client's latency test can offer a clue, but it doesn't replace an actual request from the test app.

Keep a Reproducible Setup

After a successful test, note the group, active server, proxy mode, and test app. If the test was temporary, choose “Clear System Proxy” in v2rayN or restore the system proxy settings you recorded earlier. If you changed only the app's proxy settings, restore them in the app. In v2rayNG, tap the button at the bottom again to stop the connection and confirm that the system VPN status is gone. Once you can reproduce the result with the same settings, adjust routing, DNS, or app selection one setting at a time. See the advanced manual for the order of routing changes and their effects.