CLIENT SETUP / GETTING STARTED

V2Ray Subscription Setup and Connection Guide

Follow these steps for your first setup: import a subscription → choose a proxy mode → connect → verify. If the client is installed and you have a valid subscription URL, the process should take about 10 minutes, depending on your network and configuration. This guide covers only the essential GUI steps; for a complete explanation of configuration fields, see the configuration reference.

Before You Begin: Client and Subscription URL

If you haven’t installed a client yet, visit the client downloads page to choose the right installer for your operating system, then open the app. The client reads configuration and routes traffic, but installing it doesn’t provide working servers. Get a subscription URL or server details from a service account you’re authorized to use. This guide doesn’t provide public subscriptions, and you don’t need to paste your URL into an online converter.

Once you have a subscription URL, check that your device has the correct date, time, and time zone. A significant clock difference can interfere with authentication or secure connections. Also check for other proxy software: on desktop, avoid having multiple apps change system proxy settings at once; on Android, usually only one VPN connection can be active. For your first setup, close other apps that route traffic to avoid conflicts, then follow the steps below.

Subscription URLs often contain access tokens, so treat them like account credentials. Don’t include the full URL in screenshots, public chats, or support requests. If you need help, share only the client name, where you were in the process, and the type of error. You only need to understand the difference between a subscription and a server to continue; see the glossary for terminology. There’s no need to read up on protocol details first.

STEP 01 / SUBSCRIPTION

Import a Subscription: Save the URL and Update Your Servers

First, identify what you have. An address that usually starts with https:// and retrieves an updatable server list is a subscription URL. Content starting with vmess://, vless://, or trojan:// is usually a single-server share link. They’re imported differently: add subscriptions under a subscription group, and use the clipboard import option for share links. Pasting a single-server link into a subscription URL field may appear to work, but the update will fail.

v2rayN: Add a Subscription Group

Open the Subscription Group menu in the main window, then select Subscription Group Settings and choose Add. Give the group a recognizable name and paste the full subscription URL into the address field. Check for spaces, line breaks, or punctuation added by a chat app at either end; don’t edit the URL’s query parameters. After saving, return to the main window. The URL is saved, but the server list hasn’t been fetched yet.

Next, open the subscription menu and choose the update option for the group you just added. If this is your first time and you don’t have a working connection yet, start with the option to update without a proxy. Use the through-proxy option only if your current network can’t fetch the subscription directly and you already have another working connection. Wait for the update to finish, checking the status or log area, then select the new group and confirm that server names, protocols, and addresses appear in the list.

v2rayNG: Add a Group and Fetch the Subscription

Open Subscription Group Settings from the side menu, tap Add to create a group, enter a name and subscription URL, then save. Return to the server list, open the top-right menu, and choose Update Subscription or the equivalent option. Adding a group and updating a subscription are separate steps. If you see the group name but no servers, check whether you’ve run the update before reinstalling the app.

For a single-server share link, copy the full link, open the Add menu on the main screen, and choose Import from Clipboard. Check that the server appears. A manually imported server usually won’t update through a subscription group; if the service parameters change, you may need to import it again. Don’t publicly share screenshots of the link’s QR code, as it may contain access credentials.

If an update fails, first confirm the URL is still valid and the subscription hasn’t expired or exceeded its usage limit. Then check whether the logs indicate a network timeout, certificate error, or unsupported format. Avoid adding the same group repeatedly; duplicate groups make it harder to tell which one you’re using. Once at least one server appears without obvious parsing errors, keep the list and move on. There’s no need to test every server yet.

STEP 02 / TRAFFIC ENTRY

Choose a Proxy Mode: Configure the Entry Point and Routing Separately

“Mode” can refer to two different things in a client. First, how app traffic enters the client—for example, through the system proxy on desktop or VPN routing on Android. Second, how traffic is forwarded once it enters—for example, through a proxy or directly, according to routing rules. Enabling an entry point doesn’t mean all requests use the proxy, and choosing proxy routing doesn’t mean other apps are sending traffic to the client. Separate these two layers during your first setup to avoid changing unrelated settings when troubleshooting.

v2rayN: Use the System Proxy for Your First Test

Find the System Proxy options at the bottom of the window or in the system tray’s right-click menu. Look for options such as Set System Proxy Automatically and Clear System Proxy. For your first setup, use the system proxy; there’s no need to enable TUN at the same time. Choose your entry point first. After confirming in step three that the core is running, enable automatic system proxy configuration so apps that follow system proxy settings send requests to the local listening port.

Next, review the routing options. Common rule sets distinguish between proxy, direct, and block actions; the exact labels depend on your client version. If you’re unsure what the default rules do, read their descriptions rather than assuming that “global” means every app is covered. To check whether a specific destination is reachable through your selected server, you can temporarily use a rule that explicitly routes it through the proxy. Restore your usual routing rules after the test.

The system proxy mainly affects apps that respect the operating system’s proxy settings. Some command-line tools, games, and apps with their own network stack may ignore them, so start by testing with a browser; don’t assume the server is down just because one app behaves differently. To learn more about TUN, inbound ports, or other traffic entry points, see the inbounds configuration reference. Avoid changing multiple entry points before your first connection.

v2rayNG: Check Routing Rules and App Coverage

Open Settings from the side menu and review the routing options. You can keep the version’s default rules for your first test, but be aware that some destinations may be routed directly. If you’ve configured per-app proxy settings, check that the browser you’re testing with isn’t excluded. An excluded app may connect directly even when the VPN indicator is on, so that indicator alone doesn’t prove the browser’s requests are using the proxy.

For now, avoid combining custom DNS, app exclusions, and multiple routing overrides. Keep the variables to one server, one set of understandable rules, and one test app. Once the connection works, adjust settings one at a time. For details on domain matching, IP matching, and domainStrategy, see the glossary’s routing and DNS guide and the routing reference. After checking the mode, return to the server list to connect.

STEP 03 / CONNECT

Connect to a Server: Check the Selection and Startup Logs

A server appearing in the list doesn’t mean it’s the active outbound, and a running status doesn’t guarantee that the remote server is reachable. First confirm the active server, then confirm the local core starts, and only then route app traffic through it. Choose one server with clear configuration details, and avoid switching groups or editing multiple configurations while connecting.

v2rayN: Set the Active Server and Enable the Entry Point

Find the server you want in the list, right-click it, and select Set as Active Server or the equivalent option. Some versions also support double-clicking to switch. Afterward, check the active-server indicator, status bar, or logs rather than relying only on the highlighted row. The client generates a runtime configuration for the active server and may reload the core. Wait for the logs to settle, then check for startup errors.

If the logs report that a local port is already in use, close other proxy clients and check whether another v2rayN instance is running. Don’t change all the ports just to clear the error. If you do need to change a listening port, make sure the system proxy and any apps configured to use that port are updated too. If the configuration can’t be parsed, return to the import step and check the protocol and client compatibility instead of repeatedly clicking Start.

Once you’ve confirmed the core stays running, enable the automatic system proxy you prepared in the previous section. Minimizing the v2rayN window usually leaves it running in the background, but choosing Exit stops the related services. Keep the client running while you test; don’t close it while testing in your browser. If your version requires additional permissions or components, follow the on-screen instructions, restart the client, and continue with the selected server.

v2rayNG: Select a Server and Grant System Permission

Tap the server you want on the main screen to select it, then tap the Start button at the bottom. The first time you connect, Android will ask for permission to establish a VPN connection. Confirm the app name and allow the connection. Without permission, the app can’t route traffic as described here, even if the server details are correct. If you denied the request, return to the main screen, tap Start again, and grant permission.

After starting, check the button state and the system VPN indicator, then open the client logs to look for immediate errors or repeated restarts. The indicator only confirms that local traffic routing is active; it doesn’t mean server authentication succeeded. If another VPN app is running, stop it before starting v2rayNG. For your first test, keep the client in the foreground. Once the connection works, review your device’s battery settings if you need it to keep running in the background.

A latency test returning a number doesn’t mean setup is complete. Some tests only reach the server port; others make a request through the current proxy. They measure different things. Once the local client starts normally, move on to the next step and test the full route with a real request. For a comparison of test methods, see TCPing vs. real connection latency vs. download speed tests.

STEP 04 / VERIFY

Verify the Connection: Compare Real Requests with the Logs

Open the browser you’re using for the test, start a new tab, and visit a known, working HTTPS page you’re allowed to access. Choose a page you haven’t opened before, or force a refresh, to avoid misleading results from the cache. Don’t rely on an old tab that still displays content or a video that keeps playing from its buffer. Test a new connection made after enabling the proxy.

Then check the client logs or connection records around the time of the request. If the current log level records access requests, confirm that the destination domain or address appears and use the routing log to see whether it went through the proxy or connected directly. Some versions don’t show every request by default, so the absence of a destination doesn’t automatically mean failure. You can temporarily enable the client’s access log, then restore the original setting to avoid retaining a history of destinations.

If the page loads but the routing log shows direct, that confirms the direct route works, not that your selected proxy server is usable. To test proxy traffic, use a destination that is explicitly routed through the proxy or temporarily adjust the relevant rule, then make a new request. Conversely, if a proxied destination loads but local network devices are unreachable, check your LAN direct-connection rules before switching servers.

Troubleshoot by Narrowing Down Three Areas

Check the entry point first. If the browser request never reaches the client, confirm that the system proxy is enabled on desktop and check whether the browser has its own proxy settings. On Android, check that the VPN is still connected and that the browser isn’t excluded by per-app proxy settings. Changing remote TLS parameters won’t help if the request hasn’t reached the remote connection stage.

Then check the routing. If the request reaches the client but uses the wrong outbound, review the active rule set and destination match conditions. After changing a rule, save and reload the configuration, then test with a new request; existing long-lived connections may keep using the old route. Change just one rule related to the destination and note the result. Avoid changing the server, DNS, and proxy mode all at once, or you won’t know what fixed the issue.

Finally, check the remote connection. If the request was routed through the proxy but failed, check for a connection timeout, authentication failure, or TLS handshake error. A timeout may point to an incorrect address or port, or a network reachability issue. For authentication failures, check that the subscription is valid and the account parameters are correct. For handshake errors, check the required server name, device time, and transport settings. Don’t disable certificate verification to hide the error; retrieve the correct configuration instead. For protocol-specific fields, see the complete configuration reference.

Save Your Settings and Disconnect

Once you’ve confirmed that requests use the expected proxy route, note the working subscription group, server name, and rule set—there’s no need to record full credentials. For future sessions, you’ll usually only need to update the subscription, select a server, and start the client. Revisit the mode settings only if the service parameters or your needs change. Server names may change after a subscription update, so confirm the active server rather than assuming the previous selection is still active.

When you’re done, clear the system proxy before exiting v2rayN on desktop. The client normally restores the relevant settings on exit, but check for leftover system proxy settings if it closes unexpectedly. On Android, tap Stop in v2rayNG to end the VPN connection. If your browser suddenly can’t connect after you exit, check whether it’s still pointing to a local proxy port whose client has stopped; don’t reset your entire network right away.

For terminology, see the glossary. To understand how inbounds, outbounds, routing, and dns work together in JSON, continue with the complete configuration file reference. You don’t need to write a full JSON file by hand for your first connection; start by getting the client’s basic GUI workflow working.