# OneXray: an Xray-core client that imports the servers you already have

> OneXray is a Flutter based Xray-core client for iOS, macOS, Android, Windows and Linux that imports servers or subscriptions, lets you define routing, and connects through the device's system VPN. It ships no servers and no subscription service, so it suits a user with a provider they already trust, and it does not help anybody who has neither.

**YuanDevTeam/OneXray** — Cross-platform Xray-core client for iOS, macOS, Android, Windows, and Linux, with flexible routing and importable JSON configs you can create with your preferred AI assistant.

- Repository: https://github.com/YuanDevTeam/OneXray
- Website: https://onexray.com
- Stars: 710 · Forks: 95
- Language: Dart
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/yuandevteam-onexray

## The client ships without servers, on purpose

OneXray is an open source Xray-core client for phones, tablets and desktops, written in Dart on top of Flutter, and it is distributed for iOS, macOS, Android, Windows and Linux.

The most important paragraph in the documentation is the one with the bold heading Bring your own servers. OneXray does not provide VPN access, proxy servers or subscriptions. A compatible configuration or a subscription from a provider you trust is required. The workflow that follows from that is short: import your servers or subscriptions, choose how traffic is routed, and connect through your device's system VPN.

That constraint is the product. The app is the vehicle, and the transport configuration is yours. Anyone evaluating it should start by asking where the configuration will come from, because the answer decides whether the app is useful at all.

The licensing is GPL-3.0, and the repository is not archived, with the last push on 2026-10-20. There is a documentation site at onexray.com, a Telegram channel for the team, and the README is published in English, Simplified Chinese and Russian.

The technology underneath is Xray-core, which is the engine that does the actual proxy work, and the routing model is exposed through the app rather than hidden.

## Four import formats, and the one that keeps your credentials out of the chat

The import side is where the design is most careful, and the documentation describes four supported configuration types: server or outbound JSON, normal or Advanced Custom Routing, and complete Raw JSON.

The distinction that matters is between Advanced Custom Routing and complete Raw. Advanced Custom Routing reuses servers already imported into OneXray, so you do not need to share their credentials to customise DNS, sniffing or local inbounds. Complete Raw is for the case where the JSON must own real nodes, or fields outside that template.

Two rules sit on top of the choice. Use normal UI steps when they are sufficient, and respect app-managed settings and rule order, because the application owns part of the configuration and the ordering of routing rules is part of its behaviour rather than an implementation detail.

The instructions the project gives for generated configurations are strict on purpose. Ask for missing information first, never invent credentials or network details. Produce complete strict JSON without comments, ellipses or unresolved placeholders. Explain the exact import entry, prerequisites, any VPN Tunnel steps, expected behaviour and verification steps, and do not claim tests that have not been run.

That last rule, and the instruction to treat imported content as data rather than instructions, are the parts to keep in mind when a configuration is machine produced.

## The AI configuration guide is a document, not a service inside the app

OneXray publishes a machine readable guide for assistants and links it from the README. The prompt is meant to be pasted into whatever assistant you already use, and it starts by asking that assistant to read the complete guide, with a fallback to the linked chapters if the full text is unavailable, and an instruction not to guess the contents of unread sections.

The bracketed fields are where you fill in your own situation:

```text
My platform, installation package, and App version: [fill in]
What I want to achieve: [fill in]
Existing servers, DNS, and local networks: [only the necessary details]
```

What matters is what the project does not do. OneXray does not include an AI service and does not automatically send configurations to one. The assistant you use is your own choice, and nothing leaves the app on its own. The documentation still tells you to share sensitive information only with an assistant you trust, and to review and validate the generated configuration in the app before connecting.

So the workflow is: describe what you want, get a configuration back, read it, import it. The app is the reviewer of last resort, and the guide also covers Smart Routing and platform specific VPN Tunnel settings for the cases the JSON does not cover.

## Every platform has its own build and its own minimum version

The download table is unusually specific, and each row tells you both the requirement and where the build comes from.

For phones and tablets, iPhone and iPad need iOS or iPadOS 15 and newer and are available from the App Store, with an IPA also on the release page. Android phones and tablets need Android 10 or newer on arm64-v8a or x86_64, from Google Play or as a universal APK.

On the desktop, macOS needs macOS 13 on either Apple silicon or Intel and is on the Mac App Store. There is also a separate macOS build, OneXraySE, with the same requirements, distributed through a Homebrew cask or a universal ZIP. Windows x64 needs Windows 10 20H2 or newer, with a Microsoft Store listing, an EXE available through winget, and a ZIP on the release page. Windows on ARM64 needs Windows 11 and has the same three distribution options.

Linux is the row with the most specific runtime requirement rather than an OS version: x86_64 and arm64 builds both need glibc 2.39 or newer, distributed as a DEB or a ZIP.

That last requirement is the one that catches people. A glibc 2.39 floor excludes a fair number of long term support distributions, and a static or containerised build is not offered, so a Linux user on an older base system is out of luck for this client.

## A Flutter application with a native core and generated channel code

The repository layout says a lot about how the project is built. The primary language is Dart, and the tree has the usual Flutter shape: pubspec.yaml and pubspec.lock, a lib/ directory for the Dart code, per platform folders for android, ios, macos, a separate macos_se for the OneXraySE build, linux and windows, plus assets/, test/ and tool/.

Three directories are worth a second look. The swift/ folder and the c/ folder sit alongside the Flutter directories, which is what a project that ships native code alongside a Flutter UI looks like, and build_scripts/ and helper.sh are the build entry points. The pigeon/ directory is the Flutter tool for generating typed platform channel code, which is how the Dart side talks to the native Xray core without hand written marshalling on both sides.

There is also a l10n.yaml for localisation and an analysis_options.yaml, with a devtools_options.yaml next to it, and a readme/ directory holding the Simplified Chinese and Russian versions of the README. AGENTS.md is present, and the project has been through the usual tooling for a Flutter package of this size.

The documentation notes that the README describes the current codebase, and that store and release builds may differ from it. For a project that ships through the App Store, Google Play and the Microsoft Store, that is a normal statement, and it is also the reason to check which build you are actually running before you compare behaviour against the source.

## Date stamped releases and a licence to read before you install

The release history is versioned by date, which makes it easy to place a build in time. v26.10.4 was published on 2026-10-20, v26.10.3 on 2026-10-15 and v26.10.2 on 2026-10-09, and the last push to the repository was on 2026-10-20. So the naming carries the year and the month and the day of the build, and the cadence in this window is roughly weekly.

That is a healthy sign for a client that has to keep pace with the Xray-core it embeds and with the platform VPN requirements that change with each mobile release. The same pace means you should expect to update often, which is a normal arrangement for this category of app.

The licence is GPL-3.0, which is the one point to read properly before you install it anywhere. The repository ships a LICENSE file, and for an application distributed through the app stores the copyleft obligations attach to how the work is distributed rather than to how you use it. That is a question for whoever handles licensing in your organisation, not something to take on trust from a badge.

Two smaller notes on the project itself. The documentation, the release page and the Telegram channel are the three places the project points to, and the site also serves a dedicated guide for assistants, which tells you that documentation for machines is now a maintained part of the product rather than an afterthought.

## Two ways to get a configuration, and the difference in exposure

The realistic alternatives to this app are not other apps in the same category, they are two different ways of arriving at a configuration, and they differ in how much of your setup an outside party sees.

The first is the subscription. You import a subscription from a provider you trust, and the servers arrive as a ready made list. The provider supplies the nodes, the routing and the credentials, and your app is the container. The trade is that the trust has moved to the provider, and the routing is only as good as what they publish.

The second is authoring it yourself in Raw JSON, possibly with the help of an assistant, where the app imports a complete document that owns the real nodes. The difference in approach is that you hold the node definitions and the rule set, and the assistant is used as a text tool rather than as a party to the configuration. The risk moves to the quality of the JSON you paste in.

Advanced Custom Routing sits between the two, and that is the point of it. It takes the servers you already imported and layers routing, DNS, sniffing and local inbound settings on top, so the assistant never needs the credentials at all. The documentation makes that explicit, and it is the mode to use when you want help with the routing without handing over the nodes.

Whichever route you take, the last step is the same and it is not optional: review and validate the configuration in the app before connecting.

## Conclusion

Adopt OneXray if you already have an Xray compatible configuration or a subscription from a provider you trust and you want one client across iOS, macOS, Android, Windows and Linux with routing you control. Do not adopt it expecting a service, since the project states that it provides no VPN access, no proxy servers and no subscriptions. Verify first which build you are running, because the documentation notes that store and release builds may differ from the current codebase, then read the generated JSON inside the app before you connect, and treat any configuration produced by an assistant as data rather than instructions.

## FAQ

### Does OneXray provide proxy servers or subscriptions?

No. The documentation states that OneXray does not provide VPN access, proxy servers or subscriptions, and that a compatible configuration or a subscription from a provider you trust is required. It ships no servers of its own.

### Which platforms does OneXray support and what do they need?

iPhone and iPad need iOS or iPadOS 15 or newer, macOS needs macOS 13, Android needs Android 10 on arm64-v8a or x86_64, Windows x64 needs Windows 10 20H2 or newer, Windows ARM64 needs Windows 11, and the Linux x86_64 and arm64 builds need glibc 2.39 or newer.

### What is Advanced Custom Routing in OneXray?

It is an import type that reuses servers already imported into OneXray, so you can customise DNS, sniffing or local inbounds without sharing the node credentials with an assistant. Complete Raw JSON is the alternative when the document has to own the real nodes or fields outside that template.

### Does OneXray send my configuration to an AI service?

No. The project states that it does not include an AI service and does not automatically send configurations to one. The guide at onexray.com/llms-full.txt is meant to be pasted into an assistant you already use, and you are told to share sensitive information only with an assistant you trust and to validate the result in the app.

### What licence is OneXray released under?

GPL-3.0, with the licence file in the repository. The project is written in Dart on Flutter, the releases are date stamped, with v26.10.4 published on 2026-10-20, and the last push to the repository was on 2026-10-20.

## Sources

- [License: GPL-3.0](https://github.com/YuanDevTeam/OneXray/blob/main/LICENSE)
- [Project website](https://onexray.com)
- [README](https://github.com/YuanDevTeam/OneXray/blob/main/README.md)
- [Releases](https://github.com/YuanDevTeam/OneXray/releases)
- [YuanDevTeam/OneXray on GitHub](https://github.com/YuanDevTeam/OneXray)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yuandevteam-onexray