Development
OneXray is a Flutter application with Xray-core provided through libXray and platform VPN integrations. The website is a separate static Hugo/Hextra project.
Start from the repository
- Local development setup: dependencies, native libraries, routing data, generation, and a Debug run.
- App contracts: navigation, startup, data, routing, and sharing.
- Build scripts: packaging and release boundaries.
- Windows builds: EXE/ZIP and MSIX.
Use the matching dependency revisions for your App checkout. Native libraries require a cold app restart after replacement; hot reload does not load new native code.
Runtime boundaries
Normal connections use server selections, Smart/Custom rules, and App-managed platform settings. Raw JSON has a separate compilation path. libXray is the authority for Xray configuration validation; building a valid configuration is not proof of network connectivity.
The iOS Simulator uses a Swift-only local SOCKS adaptation and is not a real VPN test. Do not document that adaptation as a public proxy mode.
Run Flutter/Dart generation, analysis, and tests serially. Keep experimental fixtures in references and avoid using a developer’s real configuration for destructive tests.
Contribute
Report an issue with platform, edition, App/Xray-core versions, and reproduction steps. Do not post private credentials.
App source · Website source · Telegram
VPN provider licensing and business inquiries
OneXray is available under GPL-3.0 with the OneXray VPN Provider Exception. VPN providers building customized clients for their own services may distribute covered OneXray code under closed-source terms. The exception covers only rights Yuan Dev Team owns or is authorized to license; third-party licenses and component obligations still apply.
Yuan Dev Team guarantees not to introduce direct third-party dependencies that require a qualifying customized client as a whole to be GPL-licensed or disclose its source under the GPL. Read the exception for its scope. For business partnerships, email yuan@yuandev.net.