Cross-Platform Setup Guides

Before You Begin: Setup Basics

Understand the Client, Core, and Connection Settings

v2rayN is a desktop GUI client that stores connection settings, starts the core, and manages proxy options. The core handles protocol parsing, remote connections, and routing rules. Project V is the broader technology ecosystem; V2Fly and Xray are separate core development branches. An open client window does not mean the core has started, and a running core does not mean system apps are sending traffic through it. Check each of these three layers separately.

Use v2rayN on desktop platforms. On Android, start with v2rayNG, which uses the Xray core; consider v2flyNG when an existing configuration specifically requires V2Fly behavior. Don't swap configuration files just because the app names look similar. Protocol support, transport settings, and extension fields depend on the client and core combination, so check compatibility guidance for the one you're using.

Check Architecture, Permissions, and Network Requirements

Before downloading, check your device's processor architecture rather than relying on the operating system name. Most desktop processors use x64, while some devices use arm64; on macOS, distinguish Apple Silicon from Intel. Android processor type, system bitness, and supported app architecture may also differ. Package format matters too: installers, disk images, and distribution packages use different installation processes and cannot be converted by changing a file extension.

Have a valid subscription you're authorized to use, or complete connection details for a single server. The client does not include a remote service. Connection details typically include the server address, port, credentials, protocol, and transport settings. TLS or REALITY may also require fields such as the server name or public key. If anything is missing, ask the configuration provider rather than guessing.

Make sure the device can access the internet, and check that its date, time, and time zone are correct. An inaccurate clock can affect certificate validation and cause authentication failures with some protocols. Confirm that a browser can open a regular webpage, then check for network sign-in portals, a system-wide proxy, another active VPN or tunnel, or security software rules. Repeatedly updating a subscription won't fix a broken underlying connection.

Know the Difference Between System Proxy and TUN

A system proxy uses the operating system's proxy settings to direct traffic from apps that honor them to a local listening port. It does not route traffic from every app: some have their own proxy settings, while others ignore the system proxy entirely. TUN uses a virtual network interface to capture eligible traffic, covering more apps but adding variables involving routing, DNS, and permissions. Enable it only after confirming that a standard proxy connection works.

Sharing a proxy over your local network is different from using it on the same device. Local use usually requires listening only on the loopback address. Enabling LAN access lets other devices reach the listening port, so you also need to consider the listen address, firewall, and access controls. Leave LAN sharing off during initial setup; don't open access to every network just to troubleshoot. If you need to share a proxy, see the LAN proxy sharing guide.

Use a Reversible Setup Process

Before installing or migrating, fully quit the client and back up its configuration directory. Backups may contain subscription URLs, credentials, and usage history, so store them somewhere secure. Note the current system proxy state, listening port, and routing choice before making changes. Redact full subscription links, server credentials, and QR codes from screenshots; anyone who gets them may be able to use the same service configuration.

Work through the setup in this order: install, import, start, test an explicit proxy, test the system proxy, then test TUN. Change one major variable at a time and note what changes. If an upgrade causes problems, compare the backup and logs instead of resetting everything to an unknown state. To roll back, quit the new client first, then restore the matching configuration copy so two processes don't write to the same directory.

Install v2rayN on Windows and Route Traffic

Choose the Desktop or Classic WPF Edition

Go to the Windows download section and choose between the v2rayN desktop edition and the classic WPF edition. The desktop edition uses a cross-platform interface; WPF retains the classic desktop experience. These are not different tiers of connection protocol, and appearance alone is no measure of performance. Choose based on your system, preferences, and required features. You don't need to install both editions to complete setup.

The main Windows download is for x64. If your device uses a different architecture, check system compatibility first; an x64 package is not a native arm64 build. Follow the installer prompts to choose a destination and install any required components. If Windows reports a missing runtime, install the appropriate component based on the error rather than copying DLLs from an unknown source. Keep the exact error message if installation succeeds but the app won't start.

On first launch, don't put the configuration directory somewhere read-only or let sync software modify it at the same time. The installation directory may differ from the user configuration directory; use the client's directory shortcut or logs to confirm the actual path. A standard system proxy generally doesn't require running as administrator. Grant elevated permissions only when explicitly prompted for a virtual interface, driver, or other privileged operation—not as a general fix.

Import a Subscription and Confirm the Core Starts

Open the subscription group settings, create a clearly named group, paste the complete subscription URL into the address field, save, and update the subscription. After a successful update, select a configuration from the list as the active one. Importing saves connection data locally; it does not confirm that the remote server is reachable. If the list is empty after an update, check the result and confirm the URL returns connection configurations rather than an account sign-in page.

After selecting a configuration, start or reload the core and check the logs for startup failures, port conflicts, or unsupported fields. If a configuration relies on Xray extensions, the selected core must support those parameters. Don't switch every core setting without a specific reason. If you have multiple groups, make sure the active configuration belongs to the group you just updated so you don't mistake an old configuration's behavior for the new subscription's status.

Test the Local Proxy Before Enabling the System Proxy

Check the local listening port in the settings. A common value is 10808, but use the value shown in your client; this is a port on your computer, not the server port. Once you know the proxy type, configure an app that supports manual proxy settings to use the loopback address and this port. After that test succeeds, set the system proxy to automatic and check whether your browser picks up the new settings.

Browser policies, extensions, and in-app settings can affect whether the system proxy works. If one browser works but another app doesn't, check whether the second app supports the system proxy before changing the remote configuration. If a command-line tool needs its own proxy settings, configure them only for the relevant process and remove them when done. System proxy settings and terminal environment variables are separate; changing one may not affect the other.

Enable TUN and Troubleshoot Windows-Specific Issues

Try TUN only if you need to capture traffic from apps that don't honor the system proxy. Grant the permissions requested by the current client, then check the virtual interface, default route, and DNS for problems. Keep routing simple during the first test and quit other virtual networking tools temporarily. If enabling TUN breaks connections that worked before, turn it off to restore network access, then investigate the logs and interface state. Don't change certificates, subscriptions, and firewall rules all at once.

Distinguish Windows Firewall prompts about outbound connections from requests to let other devices access a local service. If you're using the proxy only on your computer, you don't need to allow unrestricted inbound access just to clear a prompt. If a port is in use, close duplicate v2rayN instances and check whether an old process is still running in the system tray. After changing the port, update any apps where you entered the proxy address manually, or they'll keep using the old one.

Before quitting, clear the system proxy and then close the client normally. If the app exits unexpectedly and browsers lose access, check whether the system proxy still points to a local port that's no longer listening. Turn on auto-start only after manual use is stable, then verify that signing in starts only one instance. If a connection fails after waking from sleep, check that the basic network is back before reloading the core; the device may simply not have reconnected yet.

Before upgrading, export necessary settings and back up the configuration directory. After installation, compare the listening port, active configuration, and routing choice. When migrating between editions, not every window option has a direct equivalent; restore the connection data first, then review platform-specific settings. For the basic flow, see the proxy setup steps in the Quick Start Guide. Avoid adding new routing rules during migration.

Install v2rayN on macOS and Manage Permissions

Choose the Package for Your Mac's Chip

Check About This Mac for your chip or processor. Choose arm64 for Apple Silicon and x64 for Intel, then get v2rayN from the macOS download section. Don't infer the architecture from the year you bought the computer; different chip models may have been sold in the same year. A mismatched package may fail to open, require a translation layer, or cause other compatibility issues. Prefer the package that matches your device.

Open the disk image and follow its instructions to copy the app to the Applications folder, then launch it from there. Don't run it from the mounted disk image long term: ejecting the image, moving its path, or not mounting it after login can prevent the next launch. Don't put configuration files inside the app bundle; updates may replace its contents. User data should stay in the configuration location used by the client.

If macOS shows a security warning, check the file's source and the type of warning, then use the system's Security & Privacy controls to authorize it. A damaged-app warning, an architecture mismatch, and an unverified developer are different issues with different solutions. Don't disable system-wide security or copy terminal commands from unknown sources to remove file attributes. If you're unsure, keep the full warning text and verify the selected file on the download page.

Import a Configuration and Test the Proxy

After launching the client, create a subscription group, save the URL, and update it. If you copied the text from a notes or chat app, check for full-width punctuation, line breaks, and trailing spaces. Once the update succeeds, select an active configuration, start the core, and check the logs. macOS interface labels may differ slightly from Windows; look for the setting by what it does rather than expecting every button to be in the same place. Keep server parameters separate from local listening settings.

First test the loopback address and listening port with an app that supports an explicit proxy. Once the core is working, enable the system proxy. macOS proxy settings are tied to network services, so Wi-Fi, Ethernet, and other services may have different settings. If an app stops using the proxy after you switch networks, check the proxy settings for the current service rather than relying on the client's last displayed toggle state.

Some apps read proxy settings at launch, so you may need to reopen them after changing the system proxy. Others use their own network settings and won't necessarily follow the browser. For a reliable test, use the same destination and proxy method each time; don't mix browser cache, existing connections, and new connections. Close existing windows and test again if needed so the result reflects the current settings.

TUN Permissions and Network Changes

TUN uses a virtual network interface and system routes; the permission process depends on the client's implementation. Grant only the permissions the app explicitly requests, then check whether the core actually starts. An enabled switch in the window doesn't mean the system has created a working interface. If you see a permission error, interface creation failure, or route error, follow the logs rather than repeatedly toggling the setting.

Using a corporate network tool, virtual machine bridge, or another tunnel at the same time can cause routing or DNS conflicts. Establish a baseline with only v2rayN running, then re-enable other tools one at a time. If they must coexist, decide which addresses should connect directly and which should use another network tool. Don't delete unfamiliar system routes just to temporarily restore a webpage; this could disrupt remote access or corporate network resources.

An existing connection may stop working after waking from sleep, switching from Ethernet to Wi-Fi, or joining a network with a sign-in portal. Turn off proxy routing first and complete network sign-in, then start the core and re-enable the proxy. If the connection fails after every wake, note whether ordinary webpages open directly, whether the local port is still listening, and whether the logs show a remote reconnect. These details are more useful than simply reporting that the network is stuck.

Quit, Update, and Migrate Configurations

Before quitting normally, turn off the system proxy and TUN, and check that the system network settings have been restored. Force-quitting the app can leave the proxy pointing at a local port that is no longer listening, causing browsers to fail. Check the proxy settings for the current network service and remove only settings related to this client. If your device is managed by an organization, don't overwrite administrator-configured proxy settings.

To move to another Mac, back up your subscription and necessary settings, then install the build for the new chip. Connection configurations can be migrated, but local paths, login items, and network permissions cannot simply be copied. After migration, verify the listening address, system proxy, and TUN. Delete the old backup only after everything works. Backups containing credentials should not stay in a public shared folder; store them according to your data management practices after importing.

Install v2rayN on Linux and Configure the Desktop Environment

Check the Distribution Package Format and Processor Architecture

Open the Linux download section, choose deb or rpm based on your distribution, and check the processor architecture. Debian, Ubuntu, and similar distributions generally use deb; Fedora and similar distributions generally use rpm. Check the package management documentation for derivatives. x64 and arm64 refer to processor architectures, not package formats. A package format may be available for multiple architectures, and a successful download doesn't mean your system can install it.

Check system and processor information in Settings. If you're comfortable with the terminal, you can also run the read-only command below. Common output x86_64 indicates x64, while aarch64 usually indicates arm64. Use the distribution identifier to choose an installation method; don't infer it from the desktop's appearance. Systems with similar interfaces may use different package managers and dependencies.

uname -m
cat /etc/os-release

Open the downloaded package with your distribution's graphical software installer and review the dependency and permission prompts. If installation fails, first determine whether the cause is an architecture mismatch, missing dependencies, or another package manager process using the database. Don't force the installation past dependency errors or delete a package manager lock file while an update is running. Resolve the package system issue before trying again; that's safer than repeatedly overwriting the app directory.

Run as a Regular User and Find the Configuration Directory

After installation, launch v2rayN from the app menu as your everyday user. Don't run the entire GUI client with elevated privileges long term; it could create configuration files owned by another user, preventing normal launches from writing to them. If saving fails, check the actual configuration path and file ownership. Use the path shown by the app rather than assuming all distributions store user data in the same location.

Create a subscription group, update it, select an active configuration, and start the core. Check the logs for execution permission errors, port conflicts, or missing core files. If the package appears to be installed correctly but the app can't run the core, check security policies, mount options, and file permissions. Don't recursively loosen permissions across your home directory; locate the specific file and fix it according to your distribution's permission rules.

System Proxy Is Not a Universal Entry Point

On Linux, system proxy support depends on the desktop environment, application toolkit, and how each app is implemented. After enabling a proxy in desktop settings, some browsers may use it while terminal programs still connect directly. This can be a difference in proxy settings, not a client issue. First test the local listener in an app that supports manual proxy settings. Once the core connection works, check whether the desktop proxy was written to the location used by your current session.

Desktop apps, terminal environment variables, and background services don't usually share proxy settings automatically. Setting a variable in a terminal doesn't change the whole desktop session, and a background service may have its own environment. When troubleshooting, note which program made the request and where it gets its proxy settings. Avoid keeping multiple conflicting proxy addresses, especially after changing the listening port or uninstalling the client.

If you manually configure a SOCKS proxy in an app, check how it handles DNS resolution. Some implementations resolve names locally before sending the address through the proxy; others can send the name to the proxy for resolution. The resulting DNS behavior differs. Don't assume all SOCKS settings resolve names the same way. Check the app's options, client logs, and actual results.

TUN, Privileged Operations, and Network Management Services

TUN typically needs device and network management permissions. The client may handle this through a permission prompt or helper mechanism. Check the error first, then grant permissions through the app's current workflow. Don't assign broad capabilities to the entire app directory. Network management and name resolution services vary between systems, as do the ways routes and DNS settings are applied. Commands copied across distributions may overwrite existing network configuration.

If DNS stops working after enabling TUN, turn TUN off and check whether resolution recovers. Then inspect the system resolver, client DNS settings, and existing virtual interfaces. If local network addresses are unreachable too, check routes for private address ranges and interface priority. Virtual machines, containers, and corporate tunnels may use additional subnets; don't assume every local network uses only the range assigned by a home router.

Before setting up auto-start, make sure the app works reliably when launched manually after you sign in. A user session and a system startup service differ in permissions, environment variables, and configuration paths; a GUI client is not the same as a background daemon. Before quitting or uninstalling, restore the system proxy, disable TUN, and confirm the network works. To migrate settings, stop the process, preserve file ownership, and check paths and permissions on the new system.

If an update removes only the tray icon but the window and core still work, check whether your desktop environment supports tray icons before importing all subscriptions again. If the window won't appear, check the graphical session and startup error. Keep interface, core, and network issues separate to avoid unrelated changes. For related routing data, see the routing rule file update guide.

Install v2rayNG on Android and Keep It Running in the Background

Choose v2rayNG or v2flyNG

Go to the Android download section and start with v2rayNG. Use v2flyNG if you need compatibility with V2Fly core behavior. These are separate apps, so check subscriptions, active configurations, and background settings independently; they don't share them automatically. If you install both to compare, run only one VPN service at a time to avoid mistaking a system-stopped app for a connection problem.

Most newer phones can use arm64, but the architecture supported by the system is what matters. If you can't confirm it or installation fails with an architecture error, check the device information and consider the universal build. A universal build supports more architectures; it doesn't improve remote connectivity. Check TV devices, emulators, and older hardware separately rather than relying on the processor's advertised name.

During installation, Android may ask you to allow the file manager or browser that started the install to install apps. Grant permission only to the source you need, and revoke it afterward if appropriate. If an update fails, distinguish a signature mismatch, insufficient storage, an architecture mismatch, and a system restriction. Don't uninstall the old app without a backup; uninstalling usually deletes its subscriptions, connection configurations, and local settings.

Import a Subscription and Approve the VPN Request

Add a URL to a subscription group, save it, update the group, and select an active configuration. When importing from the clipboard, make sure you copied connection data or a subscription URL, not explanatory text from a sharing page. For QR code imports, check what it represents: a QR code for one connection may mean something different from a subscription QR code. After importing, review the configuration type and key parameters; an item appearing in the list doesn't guarantee the data is complete.

The first time you start VPN mode, Android displays a connection request. Confirm it comes from the client you just installed, then allow the VPN connection. A VPN icon in the status bar only indicates that a VPN service is active at the system level; it doesn't confirm that the remote connection works. Check the client logs and try accessing a destination. If the service stops immediately, first check permissions, the active configuration, and core startup errors instead of changing battery settings.

Android usually allows only one active VPN service per user or profile. Other network filters, enterprise access tools, and tunnels may compete with the client. If starting one app disconnects another, check the system's limits and work profile, then decide which service to keep. Don't repeatedly start multiple apps at once; their disconnect logs won't accurately show the stability of any one client.

App Routing and Proxy-Only Mode

To route only selected apps, use the app selection feature in the client. First check whether the list includes or excludes the apps you select: selecting an app might route it through the proxy or bypass the proxy. Restart the connection after changing this setting and make a new request in the target app to verify. System apps, work profile apps, and apps in different user spaces may not all appear in the same list.

VPN mode and proxy-only mode cover different kinds of traffic. Proxy-only mode mainly provides a local listening service; target apps must use that proxy themselves, so don't expect every phone app to follow it automatically. A manual proxy setting for home Wi-Fi is not equivalent to the client's VPN mode and may apply only to that network or some protocols. To compare battery use or connectivity, make sure both tests use the same mode.

Background Operation, Battery Use, and Network Changes

If the connection works with the screen on but drops when locked, first check whether the client is still running. Then review battery optimization, background activity, auto-start, and data saver settings. System labels vary, so look for the setting that allows background activity. Adjust only the restrictions the client needs and check the result; you don't have to disable power saving globally. For more detailed steps, see background operation and battery settings.

Continuous traffic, frequent reconnects, and overly frequent checks can all use more battery. When troubleshooting, note the standby conditions, network type, and whether a high-traffic app was active. A high percentage in battery stats alone doesn't prove something is wrong. After switching from Wi-Fi to mobile data, the existing connection may need to reconnect. First make sure mobile data works and the client is allowed to use it in the background.

If Android is set to always-on VPN or to block connections without a VPN, direct access may still be blocked after you stop the client. Check these system-level options when restoring network access, not just the app's own switch. Before uninstalling or changing clients, remove the relevant system binding and export any necessary settings. Exports and screenshots may also contain sensitive addresses; when sharing troubleshooting details, include only the error type, time, and redacted settings.

Import and Manage Subscriptions

Subscription URLs, Share Links, and Configuration Files

A subscription URL usually returns a set of connection configurations for centralized updates. A single share link usually describes one connection; a configuration file may also include local listeners, routing, and DNS settings. These formats aren't interchangeable based on length or appearance. Before importing, check what the selected client input expects. Don't paste a complete core configuration into a subscription URL field or use an account sign-in page as an update endpoint.

Paths and query parameters in subscription URLs often contain access credentials. Copy the full URL without removing a complex-looking suffix. Don't submit it to an unfamiliar conversion site. If the provider offers a subscription format for a specific client, use the matching format. Generic output may omit transport extensions, so review the connection parameters after importing.

Create Groups and Plan Updates

Create groups by source or purpose, using names that are easy to distinguish but don't reveal account details. For the first update, use a network path that's currently available. If updates are configured to go through a proxy, they depend on an existing proxy connection. If all existing configurations have stopped working, this can create a loop: updating requires a proxy, and the proxy requires the updated configuration. Restore an independent network path or try a direct update if the client supports it.

After updating, check that the group contains configurations, that the number hasn't changed unexpectedly, and that the active configuration is still available. A provider may change configuration IDs or remove old entries, so the previous active item may not be selected automatically. Choose a new item, start the core, and test access. Don't mix old logs with the new configuration when troubleshooting. If needed, note when the update completed and check only errors generated afterward.

Manual edits to a subscription-generated configuration may be overwritten by the next update. Keep long-term routing, listening port, and app settings in the client's separate global settings where possible. If you need to preserve a modified connection, manage it separately after understanding how updates work; it won't automatically inherit changes from the service. When mixing subscription groups with manual configurations, keep track of where each item came from.

Troubleshoot Subscription Update Errors

A timeout usually means the request didn't finish in time and may involve the underlying network, DNS, or update route. Authentication failures are more likely to involve the URL credentials or account status. A parse error means the response wasn't in the expected format. Each needs a different fix. Read the full error type, then investigate the relevant layer. Avoid repeated refreshes that may trigger rate limits, and never post an unredacted URL containing credentials.

If a browser opens the URL and displays a webpage, determine whether it's a sign-in page, an error page, or a normal subscription page. Don't paste webpage text into the client as a connection list. If the response isn't what you expected, ask the configuration provider whether the URL has expired or requires a specific output format. The client can process only supported formats; it can't turn an arbitrary account page into a connection configuration.

If importing succeeds but starting the core reports an unsupported field, check the core and protocol parameters. VMess, VLESS, and Trojan are different protocols; REALITY is a security mechanism used in some connection configurations. Renaming one doesn't convert it into another. Transport settings, server names, and credentials each serve a different purpose. Keep the original data before upgrading or switching cores, and confirm the change addresses the error in the logs.

Back Up, Migrate, and Share Only What's Needed

When migrating, use the client's built-in import and export features if available. Before copying an entire directory, quit the client and confirm the destination platform can read the same format. System proxy settings, file paths, certificate locations, and permissions belong to the local environment and shouldn't be assumed to migrate with connection data. After importing on the destination device, test one connection first, then restore groups and other settings. This makes problems easier to isolate than migrating everything at once.

If a subscription is exposed, revoke or reset its access credentials; changing the local group name does not protect it. For troubleshooting, share only the protocol type, transport, and error category. Redact server addresses, identities, subscription query parameters, and QR codes. Set a retention period for backups too; don't keep old accounts, discontinued services, and duplicate exports indefinitely.

You don't need to update subscriptions too frequently. Check how often the service configuration changes, then choose a reasonable manual or scheduled interval. Updating a subscription is not the same as checking a connection. For the basic workflow, return to the subscription import guide. If only one group fails to update, troubleshoot it separately instead of clearing the entire client.

Routing Rules and DNS Setup

Choose What to Capture Before Choosing an Outbound

Traffic capture and routing rules solve different problems. The system proxy or TUN determines whether a request enters the client; routing rules determine which outbound handles it after that. If an app doesn't use the system proxy, even a global routing rule may not see its traffic. Conversely, once TUN captures a request, routing can still send it direct, through a proxy, or block it. Don't confuse the capture method with the outbound mode.

For your first setup, use one of the client's simple routing options and confirm that ordinary webpages, local network resources, and required remote destinations are accessible as expected. Rules that bypass mainland China typically combine domain data, IP data, and routing rules; they don't make real-time decisions based on geographic location. Global proxy can temporarily reduce routing variables, but may affect local services or corporate networks. Restore rules that fit your use case after testing rather than leaving troubleshooting settings in place.

Understand Rule Order and Match Conditions

Routing rules are typically evaluated in order, and an earlier match can prevent later rules from being applied. Exact domains, domain suffixes, category databases, address ranges, and ports are different match conditions. The meaning of combining conditions also depends on the core's rule syntax; don't assume every field on a line is an alternative match. Before editing, identify what information the target request has and which outbound you want it to use.

The example below is a snippet of an Xray routing object showing how to send private addresses direct. It is not a complete, runnable configuration. When merging it, keep the existing inbounds and outbounds and make sure an outbound named direct exists. The client may overwrite manually edited content when generating its configuration, so use the relevant routing editor where possible rather than modifying a temporary generated file.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

AsIs means the routing strategy doesn't proactively resolve domains for address matching. It doesn't mean the system won't make DNS requests. Address-based rules may still match when a request already includes an IP address. geoip:private depends on the corresponding rule data, and other categories require their data files too. A missing file, an unknown category, and an incorrect rule order cause different symptoms; check the core logs to find the actual cause.

Break DNS Down into Separate Steps

A domain may be resolved by the app, the system resolver, or the client, and the DNS request itself may use a different outbound route. A browser with its own encrypted DNS adds another path. Changing DNS in the client won't necessarily control resolution in every app. First identify what initiated the lookup, then check where the request went, which route it used, and how the returned address was used for routing. Don't stop after changing a single server address.

The system proxy mainly handles traffic an app explicitly sends through it; it doesn't guarantee that all system DNS requests are captured. TUN can extend coverage, but correct DNS handling still depends on the interface, routes, and client settings. To test, follow the guide to checking DNS request routing. A test page's reported DNS exit may also be affected by caching and network services, so one result doesn't prove how every request is routed.

FakeDNS maps domains to virtual addresses so they can be restored later, mainly for specific traffic capture and routing scenarios. It's not another name for ordinary public DNS, and enabling it alone won't make every app compatible. It requires the right interception, mapping, and domain restoration steps. If an app caches a virtual address and then connects directly, the connection may fail. After enabling or disabling related features, reconnect as needed and clear relevant caches.

Maintain and Verify Routing Rules

GeoIP and GeoSite data affect which traffic category rules match, but updating the files won't fix invalid rule syntax. First check which data files the client reads and whether the update succeeded, then verify the category name and where it's used. For background, see how to update and use GeoIP and GeoSite. Referencing a category that doesn't exist won't make it work just because the name looks valid.

Add one rule at a time, make a new connection to the same destination, and check the logs to see which outbound was selected. Existing long-lived connections may keep using their old route, so refreshing the page alone isn't enough to verify a rule change. If the destination involves multiple domains or redirects, distinguish the main page, resource domains, and API requests. Part of a page loading successfully doesn't mean all related domains used the same rule.

For everyday use, keep a clear direct-route boundary for local network resources and note why each custom rule exists. Before adding complex DNS behavior, see how FakeDNS works and when to enable it. To restore networking, undo recent changes in reverse order: remove new rules, restore DNS, then change the capture method. Keeping a verified simple setup makes future troubleshooting much faster.

Common Setup Issues and Troubleshooting Steps

Identify the Layer from the Symptoms

Describe the problem in a way you can reproduce: platform, client, system proxy or TUN, which apps fail, and whether access returns when you turn off the proxy. Then check the most recent change: subscription update, port change, DNS setting, or network switch. Don't reset everything at once; you could lose clues about the cause and make it harder to restore the parts that were working.

Troubleshoot from the underlying network to the local process, then the remote connection and app behavior. First confirm the device is online, then confirm the core starts and listens on a port. Test with an explicit proxy before checking the system proxy, TUN, and routing. If a layer hasn't passed, hold off on changing higher-level settings. This avoids changing DNS to fix a port conflict or reinstalling the client to fix a stale system proxy.

Startup, Subscription, and Connection Issues

App Differences and Restoring Network Access

Record Useful Details and Keep a Way to Roll Back

Record a short section of the logs from just before and after the failure, including the error type, time, client, operating system, and traffic capture method. Redact subscription URLs, server credentials, QR codes, and account details before sharing. Describe connection timeouts, certificate errors, name resolution failures, and unsupported configuration fields separately rather than calling everything “not working.” Clear information about the affected layer is more useful than a large dump of unfiltered logs.

After fixing the issue, note the final changes in a local maintenance log and keep a copy of the settings you've verified work. If you disabled auto-start, background restrictions, or another tool, restore them one at a time and retest for conflicts. To repeat the shortest setup flow, return to the Quick Start Guide. To switch platforms or choose another package, go to the client downloads. Use these sections as a checklist for future upgrades and migrations.