v2rayN Setup Guide:
Import a Subscription and Test Your Connection

Follow this order: import a subscription → choose a proxy mode → connect → verify. If the client is installed and you have a working subscription, set aside about 10 minutes for the initial setup. Get a basic connection working before changing routing or enabling TUN.

Before you begin, make sure the client opens normally and have a subscription URL or single-server share link from a trusted source ready. The client reads configuration and forwards traffic; the installer does not include a server you can use out of the box. A subscription URL may contain access credentials, so don't share the full URL in public comments, screenshots, or online parsing tools.

01 · Import a Subscription and Check for Servers

First, identify what you have. A URL beginning with HTTPS that retrieves a set of server configurations is usually a subscription URL. A link beginning with vmess://, vless://, trojan://, or ss:// is usually a share link for a single server. The two use different import options. Don't paste a provider's login page, order page, or documentation URL into the subscription field, even if it opens in a browser.

Add a Group in v2rayN for Desktop

Open the main window and go to Subscription Group > Subscription Group Settings. Add a group and enter an easy-to-recognize note, such as “Personal use”; paste the full subscription URL into the address field. Check the start and end of the URL for extra spaces, line breaks, or punctuation added by a messaging app. Leave other options at their defaults, save, and return to the main window.

Next, choose Update Subscription from the Subscription Group menu. If the menu offers options such as “Update through proxy” and “Update without proxy,” try updating without a proxy if you haven't connected yet. Wait for the update to finish, then check the server list in the main window. Entries showing a protocol, address, or note indicate that the subscription was parsed. Saving a group name alone does not import any servers.

If you already have other subscription groups, switch to the one you just added so you don't mistake old servers for the latest update. If an error occurs, check the specific cause in the log: a connection timeout, authentication failure, and parsing error are different problems. Don't click update repeatedly or add duplicate groups to retry; that makes it harder to tell which configuration is in use.

Add a Subscription in v2rayNG for Android

Open Subscription Group Settings from the side menu, tap Add, enter a note and subscription URL, then save. Return to the main screen and choose Update Subscription from the menu; in some versions, you may need to switch to the relevant subscription group first. Servers should appear in the list once the update finishes. If the group is empty, check the update result before tapping Connect.

For a single share link, copy the full link and use the client's Import from Clipboard option. In v2rayN, this is usually in a server-related menu; in v2rayNG, it's usually in the Add menu on the main screen. Importing a single link doesn't create a subscription that updates automatically. If the server settings change, import the link again or update the settings as directed by the source.

If the update fails, first confirm that the URL is still valid, your device clock is correct, and the source doesn't require a specific network. If the subscription requires a proxy, you'll need another working connection to update it; a server you haven't imported yet can't get you through the first update. See subscription update troubleshooting. For now, don't change transport or authentication fields.

02 · Choose a Proxy Mode and Start with a Simple Setup

“Proxy mode” often refers to two separate settings. The first is the connection method, which determines how apps send traffic to the client—for example, through a system proxy, Android VPN, or desktop TUN. The second is the routing rule, which determines whether traffic that reaches the client is proxied, sent directly, or blocked. Changing routing alone won't make apps that ignore the system proxy use the proxy. Check these two layers separately during initial setup to make troubleshooting easier.

v2rayN: Start with the System Proxy

On desktop, leave TUN off for now. Find System Proxy in the main window or tray menu and choose an option such as Set system proxy automatically. This points the desktop environment's proxy settings to the local listening port; it doesn't enable additional traffic interception. If the menu includes PAC modes, skip them during the initial test to avoid adding another set of rules to troubleshoot.

Linux desktop environments don't all handle system proxies the same way. If the client says the proxy is set but you don't see a change in system settings, check the desktop environment's Network Proxy page. If you need to enter the settings manually, use 127.0.0.1 as the address and the actual listening port shown in the client's settings. Only enter that port in the HTTP or HTTPS proxy fields if the local listener supports HTTP or mixed proxy connections. Don't infer the protocol from the port number alone.

Next, check the client's routing options. Start with a rule that bypasses LAN and private addresses so devices such as local printers and router admin pages can still connect directly. Depending on the version, this may be called “Bypass LAN,” “Bypass private addresses,” or a combined option. Read the rule description before choosing. For now, don't import complex rule sets or change DNS, probing, and transport settings at the same time. That way, if something goes wrong, you can tell which change caused it.

v2rayNG: Keep the Default VPN Connection Method

For your first connection on Android, the default VPN method is usually the right choice. Start with the client's built-in routing rules and leave per-app routing off, or make sure the browser you plan to test is included in the proxy list. “Proxy only selected apps” and “Bypass selected apps” do opposite things. Choosing the wrong one can leave the client running while the browser generates no request logs.

At this stage, choose the mode without changing advanced settings. Android will ask for VPN permission when you connect in the next step. If other network tools on the device also use a VPN interface, stop them before testing v2rayNG; the system generally can't route traffic through multiple such connections for the same user at once.

Keep track of the setup you chose: system proxy plus basic routing on desktop, or the default VPN method plus basic routing on Android. In the next step, change only the server and check the connection; don't switch connection methods at the same time. Change one variable at a time so you can pinpoint the cause of any improvement or error.

03 · Choose a Server and Connect

Return to the server list and select a complete configuration from a known source. A server note is just a label; it doesn't tell you whether the server works. Ping or TCP tests in the list usually check only part of the network path. A successful result doesn't confirm protocol authentication, TLS, or access to your destination. If the client offers a real connection test or similar option, use it to narrow down candidates, but still verify the connection with an actual app in the final step.

v2rayN: Set the Active Server and Check the Logs

Open the server's right-click menu and choose an option such as Set as active server. Some versions also let you switch servers by double-clicking; follow the on-screen instructions. Confirm the active marker has moved to the selected entry. v2rayN usually generates a configuration and starts or reloads the core after a server switch, so there may be no separate Connect button. Check the log at the bottom of the window for configuration parsing errors, an exited core, or a port conflict.

If the server is active but apps still can't connect, confirm the system proxy is still set to the mode you chose. The active server, core status, and system proxy status are three separate things; one doesn't confirm the others. A tray icon or selected server can help, but neither proves that traffic is going through the proxy.

If the log says the listening port is in use, check whether you started the client more than once or another proxy tool is listening on the same port. Don't terminate an unfamiliar system process. Close duplicate instances and try again. If you need to change the port, update both the system proxy and the verification command below. For authentication failures, certificate errors, or remote connection refusals, check the server source and device clock instead of repeatedly changing the local port.

v2rayNG: Tap Connect and Approve the System Request

Tap the target server in the Android server list and confirm the selection marker is correct, then tap Connect on the main screen. The first time it starts, Android displays a VPN connection request. Confirm that the request is from v2rayNG, then approve it. Return to the client and check its status and logs. If Android says another VPN connection will be replaced, check what the current network tool is doing before deciding whether to continue.

Keep the client running after connecting; don't clear it from the background or enable extra battery restrictions yet. If the connection works during testing but drops after the screen has been locked, address background restrictions then. There's no need to disable every battery management option during initial setup. To run a real connection test, use the option available in your version. Results are useful for comparing candidate servers under the same conditions, not across different networks or times.

If a server test fails, try another server in the same subscription and leave the other settings unchanged. If every server gives the same error, check the network, system clock, subscription expiry, and client logs first. Don't assume every connection problem is caused by routing, and don't remove TLS or transport settings unless you know what they do.

If startup fails, see the troubleshooting section of the FAQ. When collecting details, note the time, client name, and exact error message. Hide subscription URLs, server credentials, and share links before taking screenshots.

04 · Verify the Proxy, Then Keep Your Settings

Verify the connection in two stages: first, check that the client can reach the server through the proxy; then confirm that your browser or other app actually uses that path. A page loading is only one clue—it could have used a direct connection or cached content. For a more reliable check, look at a new request, its routing result, and the client logs together instead of relying on an icon or a single speed test.

Send a New Request from Your Browser

Open a new browser tab and visit an HTTPS page you can access that should use the proxy under your current routing rules. Refresh if needed so you don't rely on cached content. At the same time, check the client logs for the destination domain and connection at that time. The logs can show whether the request reached the core and whether it used a proxy or direct outbound route. Some versions use less detailed logs by default; temporarily switch to info level for the test, then restore the previous setting.

A direct route in the logs doesn't necessarily indicate a problem; it may be what the current rules are supposed to do. To check the proxy exit, temporarily switch to global proxy routing so ordinary destination traffic goes through the proxy, then make a new request. Restore the original rule after testing. This changes routing, not whether the system proxy is enabled; check both separately. Don't use a local network device page to test a remote proxy, since those addresses should usually connect directly.

On Android, check the browser request and v2rayNG logs in the same way. If the client is running but the browser request doesn't appear in the logs, check whether per-app routing excludes that browser. On desktop, check whether the browser has its own proxy settings or an extension overriding the system settings. Node changes won't help until the target app is using the right connection method.

Test the HTTP Proxy Port from a Terminal

On desktop, run the command below to test the proxy explicitly. Before you do, check the client settings to confirm that the local listener supports HTTP or mixed proxy connections, listens on the local machine, and uses port 10808. If your port is different, change the number in the command. The command accesses an example domain, which may not use a remote proxy under your routing rules; check the logs to confirm the outbound route.

curl -I --connect-timeout 10 --max-time 20 \
  -x http://127.0.0.1:10808 https://example.com

If you see HTTP response headers from the destination, the local proxy listener and this request path are working. The response status doesn't have to be a specific number. Some HTTPS proxy output first shows a tunnel-establishment response; that line alone doesn't prove the destination request completed. Check the rest of the response and whether curl reports an error. If the connection is refused, check the local port and core status. If it times out, use the client logs to investigate the remote connection.

This command uses the explicit -x option, so a successful result only proves that the specified proxy path works; it doesn't confirm that the system proxy is set correctly. Conversely, if your browser works but ordinary terminal commands don't, the terminal program may simply not read the desktop system proxy. To make common HTTP tools in the current terminal use the proxy, set environment variables after confirming the port:

export http_proxy=http://127.0.0.1:10808
export https_proxy=http://127.0.0.1:10808
curl -I --connect-timeout 10 --max-time 20 https://example.com

The value of https_proxy still starts with http:// because the client provides an HTTP proxy endpoint; it doesn't declare the destination website's protocol. Environment variables affect only programs that support them and processes launched later from the current shell. They don't route traffic for every app. During testing, also check whether no_proxy or an app's own proxy settings bypass the destination.

Finish Testing and Restore Your Settings

Once the test succeeds, keep one confirmed working active server and basic routing, then try per-app routing, TUN, or custom DNS one at a time. Repeat the same checks after each change. The complete V2Ray configuration reference covers configuration fields and full examples; you don't need to edit JSON line by line for your first connection.

When you no longer need the proxy, clear or restore the system proxy in the desktop client before quitting. If you entered proxy settings manually, restore them in the desktop network settings too. On Android, tap Stop and confirm the VPN is disconnected. If you set environment variables in the current terminal, run the command below to restore the current shell. If you added them to a shell startup file, remove those settings there as well.

unset http_proxy https_proxy