Refer a friend and earn 20% of every payment they make
4TO VPN
EN$
Currency
← Knowledge base
Setup35 min read

OneXray: the detailed guide to installation, subscriptions, ping and routing

OneXray is an app for connecting to a VPN through your subscription; it works on iPhone, iPad, Android, Windows, macOS, and Linux, and it takes servers from the subscription, so you do not need to create a separate OneXray account or install Xray-core manually.

This guide walks you through your first connection, binding a device with HWID, choosing a server, checking ping, updating your subscription, and setting up rules for websites and apps.

Current as of October 28, 2026. The instructions were checked against OneXray 26.10.5. The layout depends on screen width: on a phone, the sections are at the bottom; on a tablet and a computer, they are usually on the left. The screenshots in this guide show the Russian interface; labels in the text are given as they appear in the English interface.

OneXray on a computer, tablet, and phone
OneXray on a computer, tablet, and phone

What you need

  • A device with a supported operating system version.
  • OneXray installed.
  • A valid personal 4TO subscription link.
  • An internet connection to download servers.

Quick connection

If the app is already installed:

  1. Open Servers → + → Add subscription.
  2. Enter a name, for example 4TO, and paste your link into the Subscription link field.
  3. For the first setup, leave Subscription panel → Generic and Configuration mode → By subscription format, unless you were given other settings.
  4. If the subscription requires device binding, turn on Send device identifier (HWID).
  5. Select Add subscription and wait for the download to finish.
  6. Open the subscription that appears and look at the type of entries:
    • Remnawave — select the one configuration you need, then go to Connect.
    • Regular nodes with a protocol and latency — choose one node or a suitable automatic selection mode.
  7. Select Connect, confirm the system permission if it appears, and wait for the connection status.

To check, open a website or app that needs a VPN. If the connection fails, start with the "Common problems" section at the end of the guide.

1. Where to download OneXray

Use the official OneXray website or the app's page in your system's store.

Device Requirements Installation
iPhone / iPad iOS / iPadOS 15 or later App Store
Android Android 10 or later; arm64-v8a or x86_64 Google Play or the APK from the OneXray website
Mac macOS 13 or later; Apple silicon or Intel Mac App Store or OneXraySE from the OneXray website
Windows x64 Windows 10 20H2 or later Microsoft Store or the package from the OneXray website
Windows ARM64 Windows 11 Microsoft Store or the ARM64 package from the OneXray website
Linux Kernel 5.3+, glibc 2.39+; x86_64 or arm64 DEB or ZIP from the OneXray website

The app is not supported on older 32-bit ARM Android devices. This guide does not cover a separate installation path for TVs: the official instructions are aimed at phones, tablets, and computers.

iPhone and iPad

  1. Open the OneXray page in the App Store.
  2. Tap Get or the cloud icon.
  3. Confirm the installation the way your device asks.
  4. Launch OneXray and go through the initial setup.

If the App Store says the app is not available in your region, use the separate guide on changing your App Store region.

On iPhone, the main sections are in the bottom bar. The Connect screen has the connect button, the selected server, routing, and traffic counters.

OneXray connection screen on iPhone
OneXray connection screen on iPhone

On iPad, the same functions are usually split into two columns: connection and options to the left of the statistics. There is no separate "tablet version" to look for.

OneXray connection screen on iPad
OneXray connection screen on iPad

Android: Google Play or APK through Chrome

Through Google Play: open the app page, tap Install, and launch OneXray.

Through APK:

  1. Open the official OneXray website in Chrome.
  2. Go to the Android download and download the APK.
  3. Open the downloaded file.
  4. If Android blocks installation from this source, allow it for Chrome.
  5. Go back to the APK and finish the installation.

A detailed, illustrated walkthrough for granting this permission is in the guide "How to install an APK on Android". On many devices, the relevant section starts like this: Settings → Apps → Special access. The permission is granted to the specific app you open the APK from.

When updating through an APK, install the new version over the existing one. Uninstalling the app may delete local settings and change the device identifier used by the subscription.

OneXray servers section on Android
OneXray servers section on Android

On a phone, use the bottom bar of sections. Adding a subscription is under the + button in the Servers section.

Windows

There are two installation options, and they differ in how the VPN works.

Option How it works What to consider
Microsoft Store / MSIX Uses the Windows system VPN Starting Core does not require UAC; the store manages updates
Standalone EXE / ZIP Uses native TUN Starting the VPN may require UAC confirmation

To install from the store, open the OneXray page in the Microsoft Store and press the install button.

For the standalone package, download the version for your architecture from the official website. If you chose ZIP, extract the whole archive and run the app from the extracted folder. ZIP does not create shortcuts or register links automatically.

You can change it later in Advanced → VPN tunnel → Xray outbound interface. After changing networks or connecting a different adapter, check the setting again if the VPN stops starting.

The Store version and EXE/ZIP keep their data separately. Moving between them requires transferring your settings, not just installing the other package.

macOS

On Mac, the following are available:

  • OneXray from the Mac App Store — uses Packet Tunnel.
  • OneXraySE from the official website — uses the macOS system network extension.

Install the store version the usual way. For the ZIP version, move OneXraySE.app to Applications, then launch the app.

Allow adding the VPN configuration. For OneXraySE, macOS may also ask you to enable the system extension in settings. Follow the system notification; if the system explicitly requires a restart, do it.

On a computer, the main sections are in the sidebar. For example, this is what the Smart Routing editor looks like:

OneXray Smart Routing on macOS
OneXray Smart Routing on macOS

If the screen is in Russian: Подключение — Connect, Серверы — Servers, Расширенные — Advanced, Настройки — Settings, Умная маршрутизация — Smart Routing. The language is selected in the app settings.

Linux

Before installing, check the kernel and glibc requirements: the word "Linux" alone is not enough to guarantee package compatibility.

For Debian/Ubuntu, it is easier to use the DEB for your architecture. For example, for x86_64, the command from the downloads folder looks like this:

sudo apt install ./OneXray-linux-x86_64.deb

For ARM64, you need the file OneXray-linux-aarch64.deb.

The DEB installs dependencies and gives Core the network permissions it needs. ZIP requires separate preparation from the official installation kit; after replacing Core, its network capabilities must be granted again. If you do not want to set this up manually, choose a compatible DEB.

As on Windows, on Linux you need to explicitly choose the Xray outbound interface. Linux currently has no built-in backup section like the one described later for Apple, Android, and Windows.

2. First launch and system permissions

Step 1. Go through the initial setup

Read the privacy notice and continue. Wait while the local data is prepared.

Pay attention to the choice of country or region. In OneXray, it sets the sites and addresses that Smart Routing can send directly. This is not the choice of the VPN server's country.

On Windows and Linux, also choose the outbound network interface at this step.

Press the button to go to the main screen. The wizard itself does not add a subscription or connect the VPN.

Step 2. Allow the VPN to work

The permission request may appear when you enter the main interface, before you add any servers.

  • iPhone / iPad / Mac: allow adding the VPN configuration. The device may ask for a passcode, Face ID, Touch ID, or the user password.
  • Android: confirm the system VPN connection request. On Android 17 and later, you may also need to allow local network access.
  • OneXraySE on Mac: additionally approve the network extension if macOS asks.
  • Windows EXE/ZIP: confirm UAC when it is required to start Core.

If you refused by accident, add a subscription and try connecting again with the button. If the system sends you to its settings, do what it asks and try once more.

Step 3. Check the language

If the app opened in another language, find Settings → Language, choose English, and save. Server and subscription names are not translated when you change the language.

3. How the interface is organized

Section What it is for
Connect Turning the VPN on, the selected server or configuration, routing, current traffic
Servers Subscriptions, individual nodes, favorites, search, latency testing, and sorting
Advanced VPN tunnel, platform system settings, Xray, tunnel DNS, Geodata, logs
Settings Language, appearance, app information, supported backup features

Expert mode on the connection page is for personal full Raw JSON configurations. You do not need to turn it on for a regular subscription or for choosing a Remnawave configuration.

4. How to add a 4TO subscription

You need the personal connection link, not the address of the site's home page, account area, or payment page. Copy it in full, without extra spaces or a line break.

Open the add-subscription screen

  1. Go to Servers.
  2. Select +.
  3. Choose Add subscription.
  4. Enter the Subscription name, for example 4TO.
  5. Paste the link into the Subscription link field.

Fill in the additional fields

Field What to choose for a regular setup
User-Agent (optional) Leave the default unless 4TO gave you a different one
Subscription panel Generic, unless you are specifically told to choose Remnawave
Configuration mode By subscription format for the initial detection of the content type
Send device identifier (HWID) Turn on if the subscription requires device binding
Age encryption Do not configure without the provider's instructions

Subscription panel and Configuration mode are different settings. Even if you choose "Generic", the app can recognize a received full Xray JSON and save it as a provider configuration.

What to do about HWID

If you see this message:

This provider requires a supported device identifier.

turn on Send device identifier (HWID) for this subscription and repeat the addition.

Subscription form and the error when HWID is off; the personal link is covered
Subscription form and the error when HWID is off; the personal link is covered

In the screenshot above, HWID is off, so the subscription reports an error. The switch you need should be turned on:

Sending HWID turned on in OneXray
Sending HWID turned on in OneXray

OneXray uses a random identifier for this subscription, not your phone's serial number. It is kept across regular app updates and when you turn the switch back on.

Turning HWID off or deleting the entry in the app does not by itself free the device on the service side. If you have reached the limit, check the device list in the service or contact support.

If HWID is already on and the error persists, check that the link is correct and that a device slot is available. Do not change other settings at random.

Finish adding

Select Add subscription and wait for the result. A source with your name and the received entries appears in the servers section.

For regular nodes, the latency test may continue even after the import. You do not need to add the subscription again just because the milliseconds did not appear right away.

The add menu also offers importing links, a file, and a node's JSON. On iPhone, iPad, and Android, you can scan QR codes; the camera is requested when you pick this action.

In Paste link mode, the app accepts supported node and subscription links. If you have several links, put each on a separate line. For a subscription with HWID, it is easier to open the Add subscription form directly so you can check all the fields.

OneXray link import window
OneXray link import window

A connection QR code can also contain access to your subscription. Do not post it next to the guide and do not send it to strangers.

5. Regular nodes and Remnawave configurations: what is the difference

After importing, first look at what exactly was loaded. Server choice, ping, and the available routing settings depend on it.

What you see in the list What it means How to connect
Protocol/transport, for example VLESS and TLS; after a test, latency in ms A regular node managed by OneXray Choose a node or a suitable automatic selection; routing is configured in the app
A Remnawave label, a prompt to choose one configuration A full provider configuration Choose one entry manually; its DNS and routing are controlled by the configuration

If Remnawave entries were loaded

  1. Open your subscription in the Servers section.
  2. Select the specific entry for the country or destination you need.
  3. Make sure a selection mark appears next to it.
  4. Go back to Connect.
  5. Check that the Servers line shows the name of the selected configuration.
  6. Select Connect.
Selected Remnawave configuration in the 4TO subscription
Selected Remnawave configuration in the 4TO subscription

On the connection page, Provider configuration is shown in this case. This is normal: OneXray uses the rules, DNS, and chains from the received configuration.

Connection with the provider configuration selected
Connection with the provider configuration selected

To switch servers, open the subscription and choose a different full configuration. If the VPN is already running, confirm the reconnection if the app offers it.

Can you switch to "App-managed nodes"

In the subscription settings, you can choose Configuration mode → App-managed nodes. OneXray then uses its own rules for the available independent nodes from the cache.

But this changes how the connection works:

  • The provider's full scheme, including its routing and DNS, stops being the selected way of working.
  • A standalone node cannot always be extracted from a complex chain.
  • If there is no suitable cache, you will need to refresh the subscription.
  • After changing the mode, you may need to choose a compatible server again.

For a regular connection through ready-made 4TO configurations, keep the provider mode and choose the entry you need manually. Switch to app-managed nodes when you need your own rules and the subscription actually provides usable independent nodes.

6. How to choose a server and connect

One regular node

  1. Open Servers and your subscription.
  2. Select the node you need.
  3. Go back to Connect.
  4. Choose Smart Routing for everyday use or All via VPN for a simple check of the selected server.
  5. Select Connect.

A fixed single server stays a single entry server: choosing "2" or "3" in the automatic entry server options does not turn it into several servers.

Automatic selection of regular nodes

OneXray can choose automatically among suitable regular nodes, within a subscription or from your manual additions. This requires usable nodes with availability and latency test results.

If you have only one working entry, start with one entry server. Requesting two or three entry servers when there are not enough candidates can prevent the connection.

Updating the subscription or running a new test does not mean the working server is switched immediately. A configuration that is already running is not replaced silently.

Favorites, search, and manual groups

Use the star to move frequently used entries to favorites. Search helps you find the name you need in a large subscription.

In version 26.10.5, nodes you added manually can be organized into named groups and reordered. This only organizes the list: a manual group does not become a separate automatic connection pool. The mode that uses all manual servers still covers manual nodes from different groups.

On a tablet or a wide window, the list of sources and the contents of the selected source can be visible at once:

Subscriptions and the server list on a wide OneXray screen
Subscriptions and the server list on a wide OneXray screen

How to make sure the VPN works

After connecting, check three things:

  1. The app shows the connected state and the Disconnect button.
  2. The server or configuration you intended is selected.
  3. The site or app you need actually opens.

The counters show the speed and volume of the current connection. Zero traffic at an idle moment is normal: open a page and see whether the values change.

7. How to see ping and check latency

In OneXray, the familiar word "ping" means a latency test of an HTTP request through a node. The app measures the time until the response headers are received. This is not an ICMP ping and not a download speed measurement.

Test all regular nodes in a subscription

  1. If possible, disconnect a running VPN first so it does not distort the path of the test request.
  2. Open Servers.
  3. Go into the regular subscription you need.
  4. Select Test servers in the subscription's actions block. You can also open the same command through ⋯ on a regular subscription.
  5. Wait for it to finish. Tests run in a queue, so a large list does not fill in instantly.
  6. Look at the ms values next to the nodes.

If the VPN is running, OneXray warns that it may affect the result. You can cancel or choose Continue test. Continuing the test does not turn off or switch the VPN by itself.

Retest a single node

  1. Open the subscription's node list.
  2. Select ⋯ to the right of the regular node you need.
  3. Choose Test again.
  4. Wait for the latency label to update.

If the node is labeled Remnawave, this item does not exist for a regular test — the reason is explained below.

Where to see the result

The result is shown in the node's label. For a selected regular node, it can also appear in the server card on the connection page.

Latency values in milliseconds next to regular OneXray nodes
Latency values in milliseconds next to regular OneXray nodes

The current version uses the following labels:

Result Meaning in OneXray
Fast · … ms A successful test with latency up to and including 500 ms
Slow · … ms A successful test with latency above 500 and up to and including 1000 ms
Available · … ms A successful test with latency above 1000 ms
No result The node has not been tested yet, or the test has not finished
Error / timeout The test request did not complete successfully

These labels are the app's internal categories. For example, 400 ms may count as a "fast" result in the interface, but for calls and games that latency is still noticeable.

How to sort by ping

Open Servers, select the sort icon (an arrow with bars), and choose Latency.

Nodes with successful results come first, from lower latency to higher. Then come untested ones, failed ones, and full provider configurations.

How to change the test settings

Open Advanced → Xray → Speed test.

Here you can choose:

  • A preset test address from Cloudflare or Google.
  • Your own valid HTTP/HTTPS URL.
  • A timeout from 3 to 8 seconds.

By default, Cloudflare and a timeout of 5 seconds are used. Changes apply to the next tests without reconnecting the VPN.

If all nodes suddenly time out, try a different preset test address. The problem may be the availability of the test site, not all servers at once. To compare servers, use the same address and the same network.

Why Remnawave has no ping

For such a list:

  1. Choose one configuration manually.
  2. Connect.
  3. Check that the sites and apps you need work.
  4. If the quality is not good enough, disconnect and try another configuration.

If you specifically need the built-in comparative node test, you need a suitable App-managed nodes mode with independent nodes. Switching to it is described above; it does not preserve the full routing approach of a full configuration.

If the provider built its own checks into the configuration, that configuration controls them. They do not automatically turn into regular ping values in the OneXray list.

"Lowest latency" while the VPN is running

This is a separate function for regular nodes in Smart Routing or custom routing.

If at least two active proxy routes are configured, you can choose Proxy selection → Lowest latency in the routing editor. The app tests the chains of the current connection and directs new proxy connections through the chain with the lowest measured latency.

The connection page then shows information about the active-chain tests. These results:

  • Apply to the current connection, not to the whole subscription.
  • Do not overwrite the results of the manual test of the server list.
  • Do not move already open connections to another chain.
  • Do not trigger a switch to a direct connection just because a test request failed.

With one entry server there is nothing to compare. For your first connection, keep one entry, make sure it works, and only then try several.

How to choose based on the results

Lower latency usually means a faster response, but it does not guarantee a high download speed or access to a specific service. Compare several available servers on your own network and check the scenario you need: video, calls, browsing, or file downloads.

8. Routing: which mode to choose

This section applies to regular nodes managed by OneXray. If the connection page shows Provider configuration, the provider's scheme is applied; the local Smart Routing and Custom Routing settings return when you choose compatible regular nodes.

Mode Behavior When to use
Smart Routing Selected local resources and categories go directly, all other traffic goes through the VPN Everyday use
All via VPN Internet traffic is sent through the selected node, with system exclusions respected Checking a server and tasks that need an exit through the VPN
Custom Routing Traffic is handled by your rules from top to bottom Individual exceptions, your own domains and subnets

To change the mode, open Connect → Traffic method and choose the option you need. Smart Routing and saved custom routes have a separate edit action.

If you are changing a running connection, save the settings and confirm the reconnection. During such a change, the old VPN is stopped first; if the new configuration fails to start, the previous connection is not restored automatically.

"All via VPN" and system exclusions

This mode does not override the operating system's settings. For example, an app excluded from the VPN on Android will keep bypassing the tunnel. Networks excluded by Apple or Windows system policy are also handled before the Xray rules.

If a specific app still goes direct, check the system exclusions, not only the mode on the connection page.

9. How to set up Smart Routing

  1. Open Connect → Traffic method.
  2. Find Smart Routing and open its editor.
  3. Check the direct region and the switches.
  4. Select Save.
  5. Confirm the reconnection if the VPN is already running.
OneXray Smart Routing settings on a phone
OneXray Smart Routing settings on a phone

Direct region

The region sets the categories of domains and IPs that should bypass the VPN. Choose it for your task. For direct access to Russian resources, you need the corresponding region, not the country of the VPN server you selected.

The classification is based on GeoSite/GeoIP. It may be incomplete: a particular site sometimes needs its own rule.

Main switches

Setting What it does
Direct local network and private addresses Lets you reach the router, NAS, and other local addresses directly
Direct Apple services Sends suitable Apple services over the direct path
Direct Windows services Sends Microsoft/Bing categories directly; the built-in GitHub rule takes priority and goes through the VPN
Use local DNS for direct traffic Uses a separate direct DNS for suitable domains
Block common ad domains Turns on blocking by built-in categories
Use FakeDNS Uses virtual IPs to restore domains and for routing
Use Fragment Turns on TLS handshake fragmentation in a supported scheme

To start, leave FakeDNS and Fragment off. Turn on ad blocking if you like; if sign-in, payment, or a particular site breaks afterward, turn it off and check again.

Fragment can help on some networks, but it can increase connection time and does not guarantee access. It does not replace a working subscription or a compatible server.

How many entry servers to choose

For automatic selection or a group, you can set 1, 2, or 3 entry servers. This sets the available entries and how new connections are distributed, not a promise of a two- or three-fold speedup.

Start with 1. For several entries, first check that the selected source has enough suitable regular nodes.

In the Proxy selection field, Round robin and Lowest latency are available. The latter compares active chains, as described in the section about ping.

Final exit

In Smart Routing, you can add an optional final exit. The path then becomes: device → entry server → final exit → website.

For a regular connection, leave No additional exit (recommended). An additional chain requires compatible nodes, can increase latency, and is not needed for a standard subscription.

10. How to create your own rules for websites

For form-based rules, use a normal configuration, not advanced JSON.

  1. Open Connect → Traffic method.
  2. In the Custom Routing section, select New custom route.
  3. Choose Normal configuration.
  4. Enter a clear, unique name, for example My rules.
  5. Leave one entry server for the first test.
  6. Select Add rule.
  7. Specify the condition and the action.
  8. Save the rule, then be sure to save the entire route with the button at the bottom.
  9. Choose the route you created on the connection page.

In the app, you can create up to three custom routes in total, counting both the normal and advanced types. The actual servers are chosen separately on the connection page.

OneXray custom route editor
OneXray custom route editor

Example: one site direct, everything else through the VPN

Suppose the site example.com should open directly. Here it is a placeholder domain: replace it with your own.

In a new rule, set:

Field Value
Rule name This site direct
Websites and domains domain:example.com
Other conditions Leave empty
Then Direct

Save the rule and the entire route. With this rule, the chosen domain and its subdomains go directly; if nothing else matches, the regular route uses its standard proxy path.

To force the same domain through the VPN, choose the action Use VPN. To block it, choose Block.

How to write domains

Entry What it means
domain:example.com The domain and its subdomains
full:login.example.com Only the exact name login.example.com
geosite:CATEGORY A domain category from the installed GeoSite; choose an existing suggestion

Do not paste the full page URL with https://, a path, and parameters into the domain condition field. The rule needs a domain in a supported format.

A string without a prefix may mean a keyword search. For a predictable rule, use domain: or full:.

Example: local subnet direct

For a separate subnet, create a different rule:

  • Name: Local network.
  • The IP addresses or ranges field: the subnet you need, for example 192.168.1.0/24.
  • Action: Direct.

This example only applies when your network actually uses that subnet. If you need access by internal names, check DNS separately.

Why rule order matters

Rules are checked from top to bottom. The first matching one applies.

For example, an exception for a specific domain must sit above a more general rule that already covers that domain. On a computer, change the order by dragging; on a phone, use the move handle in the list. After the change, save the entire route.

OneXray rule editor on Windows
OneXray rule editor on Windows

A common mistake: domain and IP in one rule

If you need "this domain or this subnet", create two separate rules. The values within a single regular domain list can be used as alternatives.

11. How to exclude apps from the VPN on Android

On Android, there is a separate choice of which apps go into the tunnel.

Open Advanced → VPN tunnel → Android system VPN → VPN app scope.

Mode How it works
All apps All eligible apps go through the tunnel
Only selected apps Only the marked apps go into the tunnel
All except selected apps The marked apps bypass the tunnel

Exclude a banking app

  1. Choose All except selected apps.
  2. Find the app by name.
  3. Mark it in the exclusion list.
  4. Save your changes.
  5. Reconnect the VPN.
  6. Fully close and reopen the excluded app.

Keep the VPN for the browser only

  1. Choose Only selected apps.
  2. Mark the browser you need.
  3. Save the selection and reconnect.

This mode requires at least one installed app. An empty list does not mean "all apps".

The include and exclude lists are saved separately. When you switch modes, check which apps are marked: the old selection from the other mode does not necessarily disappear.

App selection determines what enters the tunnel. Smart Routing or custom rules then decide how to handle that traffic. That is why an app in "Only selected apps" mode can still reach some sites directly under the route rules.

On iPhone and iPad, OneXray has no equivalent regular app list. For these devices, use the supported domain, network, and system settings.

12. DNS, FakeDNS, and tunnel settings

Which DNS settings exist

OneXray has several different levels of DNS:

Setting What it is for
Proxy DNS in the route DNS queries over the proxy path
Direct DNS in the route Domain resolution for direct rules
Tunnel DNS in the advanced settings Platform tunnel parameters
DNS of a full provider configuration The scheme from the received full Xray JSON

If internal names of your home or work network do not open, start with the route's local DNS. For example, you may need your router's or your organization's DNS. Changing only the tunnel DNS does not replace this setting.

In regular Smart Routing and custom routing, you can set a primary and fallback DNS, as well as caching. Keep the working defaults unless you have a specific task or a diagnosed problem.

When you need FakeDNS

FakeDNS helps restore domain names for rules by using virtual IPs. It is an additional mechanism, not a universal fix for the internet.

In current regular routes it is off by default. If you turn it on, do not turn off the traffic analysis it requires: the interface has related restrictions.

After the VPN is stopped or restarted, the browser and the system may keep old DNS responses for a while. If the problem started after you changed FakeDNS, restore the previous value, reconnect, and reopen the app. Sometimes you need to refresh the network connection to get fresh DNS responses.

Do not change several settings at once

If the connection already works, change one setting at a time and check the result. Changing DNS, FakeDNS, Fragment, IPv6, and the route all at once makes it much harder to find the cause of a failure.

If you were given a separate full Xray JSON

A full configuration file and a single node's JSON are imported in different ways. For a separate full Xray JSON, open Connect, turn on Expert mode, go to the Raw JSON selection, and select Add Raw JSON. Enter a name, import the file or paste the contents using the clipboard action, then save and choose the configuration.

A personal Raw configuration sets its own servers, DNS, and routing. It is not merged automatically with the selected regular nodes or Smart Routing rules. A successful save validates the configuration but does not guarantee that its servers are reachable.

You can add up to three personal Raw configurations. Remnawave entries received inside a subscription do not count toward this limit and are chosen without Expert mode. Do not copy them into Raw just to connect: such a personal copy is detached from subscription updates.

13. iPhone, iPad, Mac, and Windows specifics

Apple: connect on demand

The settings are in Advanced → VPN tunnel → Apple system VPN.

You can set automatic behavior for Wi-Fi networks: connect on some and disconnect on others. Enter the exact network name — the SSID. One network must not be in both lists at once.

For cellular on iPhone and Ethernet on Mac, the corresponding system actions are available. Save the settings and check the transition between networks.

This is an on-demand connection mechanism, not a guarantee of an uninterrupted tunnel under all conditions.

Apple: "Capture all traffic"

This is a system tunnel setting, separate from the All via VPN mode on the connection page. It changes what the operating system passes into the tunnel.

When it is on, the supported system exclusions are available. Without a specific need, leave the defaults: a wrong combination can affect the internet, local devices, and system services.

With full capture off, you can set networks to bypass the VPN. Such exclusions take effect before the Xray rules and do not configure DNS for internal names automatically.

iPhone / iPad: hiding the VPN icon

The Apple system settings have a Hide VPN icon option. It is off by default and works through quirks of system routing. The result depends on the iOS/iPadOS version and may affect switching between networks.

For your first connection, leave it off. The presence or absence of the icon in the status bar does not replace checking the status in the app.

Computers: closing the window and quitting

Closing the window usually hides OneXray. It is not the same as disconnecting the tunnel.

  • On Mac, a regular quit may leave the VPN running. To stop it, use the disconnect button or the quit command that also stops the VPN.
  • In Windows Store/MSIX, a regular quit may also leave the system VPN active.
  • In Windows EXE/ZIP, the quit command stops the VPN.

If your goal is to disconnect for certain, first select Disconnect and check the result.

14. How to update a subscription and see its expiration

Update manually

  1. Open Servers.
  2. Select ⋯ on your subscription.
  3. Choose Check for updates.
  4. Wait for the result.
Subscription actions: update and edit settings
Subscription actions: update and edit settings

Check for updates downloads the subscription contents. Test servers tests regular nodes. These are different actions. The menu of a full provider configuration has no regular latency test.

Open ⋯ → Edit subscription, fix the field you need, and save. Then run Check for updates to fetch data with the new settings.

Saving the form does not by itself mean that the nodes have been reloaded. A running connection also does not have to switch immediately.

See traffic and expiration

If the provider supplies this information, the subscription card shows used and remaining traffic, the limit, and the expiration date.

This is information as of the last subscription update, not a real-time counter. To refresh it, update the subscription. If the field is missing or says "Not provided", you cannot conclude that the plan is unlimited.

Do not confuse these values with the statistics of the current connection on the main screen.

Automatic updates

Open Advanced → Xray → Data updates. Subscriptions and Geodata have separate switches and intervals: 1 day, 3 days, or a week.

Automatic subscription updates do not require a running VPN. Automatic Geodata updates run while the VPN is connected. If the app is closed or suspended, running exactly on time is not guaranteed.

A failed update should not replace working data with an empty list. If an error appears, first work out its cause while keeping the existing entry.

App update

OneXray itself is updated separately from subscriptions and Geodata: through the store or with a new official package. Version information is in the About OneXray section.

When upgrading from much older versions, keep in mind the interface change: the current four sections appeared in version 26.9.1. Old instructions with Home, Profile screens and a separate Direct mode may no longer apply.

15. What Geodata is and when to update it

Geodata is a set of databases of domain and IP categories for routing. They do not contain your subscription and do not replace VPN servers.

The section is in Advanced → Xray → Routing data (Geodata). The standard GeoSite and GeoIP files are updated together.

Updating is useful if a category you need has changed or your rules use an outdated classification. But it will not fix an expired subscription, a wrong HWID, or a missing VPN permission.

If a configuration refers to your own data file that is not on the device, you need to get it before starting that configuration. OneXray does not delete the missing rule and does not download it silently at the moment of connection.

If the source is unreachable without a VPN, use another working configuration to download it, then return to the one you need.

16. Backup and moving to another device

On supported platforms, open Settings → Data → Backup & restore.

Platform Where you can save
iPhone, iPad, Mac iCloud Drive or a file chosen through the system dialog
Android A file through the system document picker; a cloud provider if it is available in that dialog
Windows A folder synced by OneDrive
Linux This built-in section is currently unavailable

Create a backup

  1. Choose the storage location and file.
  2. If the file is empty, the app creates the first backup.
  3. If it already has content, choose carefully between restoring and overwriting.
  4. Check that the save succeeded.
  5. If you are moving to another device, make sure the file is available and readable there.

Usually the file OneXray-backup.json is used. Later writes replace its contents: this is not a version history and not an automatic merge of settings from different devices.

Restore

  1. Open restore and choose the backup file.
  2. Look at the preview.
  3. Confirm the replacement only after checking: restoring replaces the managed configurations rather than merging them.
  4. Update the restored subscriptions to download servers.
  5. Choose the server or configuration again and check routing.
  6. Grant the required permissions on the new device and connect manually.

The subscription node cache is not included in the backup. For Remnawave configurations, this also means you need to update the subscription after restoring. Ping results, the current connection selection, and device permissions are also not carried over as a ready, working session.

Automatic backups have their own interval of 1, 3, or 7 days. It does not depend on Geodata updates and does not require a connected VPN, but the app must get a chance to run the schedule check.

17. Common problems

"This provider requires a supported device identifier"

Turn on HWID for the subscription in question. If the entry has already been created, save the change and run Check for updates. If the message remains, check the device limit and contact support with the text of the error, with your link hidden.

"Device limit" or a registration error

Check the devices on the service side. Deleting and adding the subscription again can only increase the number of registrations. Turning HWID off does not delete the existing entry with the provider.

"No available entry servers" even though servers are visible

First look at the list labels:

  • If it says Remnawave, choose one configuration manually instead of the general automatic selection.
  • If these are regular nodes, wait for the latency test or run it manually.
  • Check that the selected source contains working regular nodes.
  • Reduce the number of entry servers to 1 if there are few suitable candidates.

Servers have no ping values

For regular nodes, run Test servers, wait for the queue, and, if needed, change the test address in Advanced → Xray → Speed test.

For full Remnawave configurations, the absence of regular ping is expected. They are checked by connecting to the selected entry, as described in the separate section.

The subscription does not load or the list is empty

  1. Check that you pasted the whole personal connection link.
  2. Check the subscription's expiration and availability in the service.
  3. Make sure HWID is on if it is required.
  4. Restore the default User-Agent if you changed it without the provider's instructions.
  5. Check that the panel and mode match the subscription format.
  6. Retry the update on a different network or through another available working connection.

OneXray does not convert arbitrary configurations from other clients. For example, a ready-made sing-box JSON cannot be considered a compatible Xray JSON just because the file extension is the same.

"No cached configurations for this mode" after changing the mode

Refresh the subscription. If there is still no suitable data for the mode, return to the original mode or request a compatible format. Do not try to take apart a complex provider chain by deleting its dependencies.

The VPN is connected, but the site I need does not open

  1. Check the internet with the VPN off.
  2. Try a different server or a different full configuration.
  3. For a regular node, temporarily check All via VPN.
  4. Check app exclusions on Android and excluded networks in the system settings.
  5. If you turned on ad blocking, FakeDNS, or Fragment, restore the previous values one at a time.
  6. If the problem involves internal names, check the route's local DNS.

In provider mode, do not look for a fix in the inactive Smart Routing switches: the connection uses the received configuration.

The tunnel does not start on Windows or Linux

Check the Xray outbound interface. After an adapter change, the saved interface may have disappeared. For Windows EXE/ZIP, also check whether UAC was confirmed; for Linux, check that the package is installed correctly and that Core has its network permissions.

Android turns off the VPN after the screen locks

Check OneXray's background restrictions in your phone's settings. On some firmware, you need to allow background activity and remove the strict battery restriction for the app. Section names depend on the manufacturer.

Also make sure that another VPN or the system always-on VPN mode does not conflict with OneXray. After changing the settings, connect from the app and check that it works after the screen locks.

Geodata file not found

Open Advanced → Xray → Routing data (Geodata), download the missing source, and start again. Restoring from a backup brings back the source information, but not necessarily the files themselves.

The connection disappeared after changing settings

When you reconnect, the previous VPN is stopped first. If the new start failed with an error, read the error and fix the cause, or manually choose the previous working settings and connect again.

18. What to send to support

To help find the cause faster, prepare:

  • Device model and OS version.
  • OneXray version.
  • Installation type on Windows or Mac, if relevant to the error.
  • The exact text of the error.
  • At which step the problem occurs: subscription loading, HWID, node selection, connecting, or opening a particular service.
  • Network type: Wi-Fi or mobile data.
  • The type of entries received: regular nodes or Remnawave.
  • The latency test result, if it is available for this type of entry.

If needed, logs are in Advanced → Xray. In OneXraySE for macOS, the file logs section is hidden.

  1. Install OneXray from an official source.
  2. Go through the initial setup and grant the system permissions.
  3. On Windows/Linux, choose the outbound interface.
  4. Add your personal subscription and turn on HWID if it is required.
  5. If the entries are labeled Remnawave, choose one configuration manually and connect.
  6. If these are regular nodes, wait for the latency test, choose one node, and start with one entry.
  7. Check the sites you need, then configure routing and exclusions if necessary.
Was this article helpful?
OneXray: the detailed guide to installation, subscriptions, ping and routing