A private, cross-platform Xray-core client for your own nodes, subscriptions, and configurations.
Documentation · Development Setup · Telegram · Releases
OneXray lets you bring your own compatible server configuration or HTTPS subscription, organize nodes, and control traffic with structured Xray Profiles and routing tools.
OneXray is a client-only app. It does not provide VPN or proxy servers, subscriptions, or network access. It requires no account and contains no advertising, analytics, tracking, telemetry, or crash-reporting services.
- Cross-platform TUN — iOS, macOS, Android, Windows, and Linux.
- Flexible configuration — Simple Profile, reusable Xray Profiles, Full Config, and Raw JSON.
- Routing control — switch between Rule, Global, and Direct behavior from Home.
- Import and organize — supported share links and HTTPS subscriptions from QR codes, images, files, or the clipboard.
- Local tools — node ping, Xray logs, GeoData and rule-set management, backup, and restore.
- Platform integration — Android Per-App VPN, Apple On Demand, desktop tray controls, and outbound-interface selection.
When adding or editing an HTTPS subscription, open Encryption and either
enter an existing age key pair or generate an X25519 or Mihomo-compatible
Hybrid key (ML-KEM-768 + X25519). OneXray sends only the saved public
recipient as X-Age-Public-Key; the secret key remains local and the pair is
reused for automatic refreshes.
HTTPS is still required. OneXray backups are not encrypted and include the age key pair so restored subscriptions remain usable; store backup ZIP files carefully.
OneXray can share and import content through its proprietary onexray:// URLs:
onexray://onexray.com/config/add?type=outbound|profile|full|raw&data=<percent-encoded-base64-json>#Name
onexray://onexray.com/sub/add?url=<percent-encoded-https-url>[&age=x25519|hybrid]#Name
onexray://onexray.com/dat/add?type=domain|ip&url=<percent-encoded-https-url>#Name
When a shared config references custom GeoData stored in OneXray, matching GeoData links are placed before the config link.
Only the types shown above are supported. Legacy type=setting, backups, and
other commands are not accepted. An age subscription link generates a new
local key pair, sends only its public key for the first download, and stores
the pair when the subscription is imported successfully.
Android, iOS, and installed macOS apps register the scheme directly. On Windows and Linux, use the EXE/winget or DEB package; ZIP packages do not register the scheme automatically. The Mac App Store app and OneXraySE share the same scheme, so installing both can make macOS choose either app as the handler.
| Platform | Requirements | Download |
|---|---|---|
| iOS | iOS 15.0 and above, arm64 | App Store, IPA |
| macOS (Mac App Store) | macOS 13.0 and above, Apple silicon or Intel | App Store |
| macOS (Outside App Store) | macOS 13.0 and above, Apple silicon or Intel | Homebrew: brew install --cask onexrayse, Universal ZIP |
| Android | Android 10.0 and above, arm64-v8a or x86_64 | Google Play, Universal APK |
| Windows x86_64 | Windows 10 or Windows 11 | winget: winget install --id YuanDevLLC.OneXray -e, EXE, ZIP |
| Windows ARM64 | Windows 11 | winget: winget install --id YuanDevLLC.OneXray -e, EXE, ZIP |
| Linux x86_64 | GLIBC >= 2.39 | DEB, ZIP |
| Linux arm64 | GLIBC >= 2.39 | DEB, ZIP |
The Mac App Store build is a separate store package. Homebrew and the Universal ZIP use the same Developer ID macos_se package and install OneXraySE.app.
brew install --cask onexrayse
brew uninstall --cask onexrayse- Download and extract
OneXray-macos-universal.zip. - Move
OneXraySE.appto/Applications. Do not run it directly from Downloads or another folder; macOS requires an app containing a System Extension to be installed in a system Applications directory. - Open OneXraySE from Applications and accept the macOS launch confirmation.
For the first VPN connection:
- Import a subscription or node, select a node, and click Start.
- Open System Settings > General > Login Items & Extensions.
- Under Extensions, open Network Extensions, enable OneXraySE, and click Done.
- If Privacy & Security also shows an approval request, click Allow and restart the Mac if requested.
- Return to OneXraySE and click Start again.
To update the ZIP build, quit OneXraySE, replace the existing app in /Applications with the newly extracted OneXraySE.app, and reopen it. Approve the System Extension update if macOS asks.
See Installing System Extensions and Drivers and Change Login Items & Extensions settings.
Winget automatically selects the x86_64 or ARM64 installer for the current device.
winget install --id YuanDevLLC.OneXray -e
winget uninstall --id YuanDevLLC.OneXray -eAndroid builds support arm64-v8a and x86_64. 32-bit ARM devices are not supported.
If the App Store is unavailable for your Apple ID, download OneXray-ios.ipa and install it with AltStore or another compatible sideloading tool.
Self-installing the IPA requires re-signing both OneXray and its Packet Tunnel extension with a provisioning profile that authorizes the Network Extension capability. Apple does not support this capability for free Personal Team accounts, so a paid Apple Developer Program membership is required. Without it, the app may open and ping nodes, but the VPN cannot start. See Apple Developer Forums and Supported capabilities (iOS).
For a DEB package:
sudo apt install ./OneXray-linux-x86_64.deb
sudo apt remove onexrayFor a ZIP package, run these commands from the directory containing OneXray:
sudo apt install -y procps libcap2-bin libayatana-appindicator3-1
sudo setcap cap_net_admin,cap_net_raw+eip OneXray/bin/OneXrayCoreGNOME users should install the AppIndicator extension. Linux arm64 currently falls back to English for CJK locales.
Contributions are welcome:
- Star this repository.
- Improve the documentation.
- Share routing templates through OneXray/Routing.
See Development Setup before building the app locally.
OneXray is licensed under the GNU General Public License v3.0.