Supported Xray configuration formats
These configuration contracts describe OneXray 26.11.4. See upgrading for changes from previous versions. Connection backup is a separate restore format, not a fourth configuration-import type.
OneXray supports outbound, Custom Routing and Raw JSON imports. Each import type has its own fields and requirements; choose the type that matches the task.
| Capability | Behavior |
|---|---|
| Outbound / Custom / Raw import | Supported |
| Custom domain, target IP, port, network | Supported |
Custom local DNS via app-dns-direct |
Supported |
Custom protocol and localOS |
Supported |
Smart/Custom FakeDNS switch and app-dns-fake |
Supported; off by default |
| Advanced Custom DNS, sniffing, auxiliary outbounds and local inbounds | Supported through a separate JSON template |
| FakeDNS recovery on a newly generated Raw inbound | Enabled when Raw declares a FakeDNS server or pool; existing sniffing stays unchanged |
| GitHub proxy priority with Microsoft bypass | Supported; precedes direct rules |
Older versions may not support every field described here. If an option is missing or a supported field is rejected, update the App first. Never silently drop conditions to make a configuration import; explain the limitation and agree on an alternative if the user must keep an older version. Raw JSON is not an automatic workaround for missing native integration.
Traceable sources
- The configuration contracts define the App import boundaries. Example validation provenance is recorded in the manifest below.
- Get the App through the installation guide.
- Core used for this documentation’s example checks: libXray commit
c145d94071088cebd445d7b0f4b1bea35732011e, Xray-corev1.260327.1-0.20260908222543-52a412d9e2f5. - Machine-readable example manifest records import types, dependencies and replacements per file.
The current upstream manual may describe fields newer than an installed App’s Core. OneXray’s envelope and ownership rules take precedence for App imports; protocol validity is decided by its bundled libXray. Do not mix syntax from unrelated clients or old VMess QR-code JSON into these documents.
The current contract was reviewed on 2026-11-13 against App 26.11.4 source a9c690c3db9818a6c4fc78b74794967553d73048, compared with v26.11.3 (2c66a8bf2277d08aac408d2984e459a3576bbf12). Connection selection, import formats, DNS ownership and backup-v1 remain unchanged; the update changes setup, session presentation, shared UI and desktop integration. The example manifest retains its earlier native-validation provenance; this documentation review does not rerun those examples.
Limits and required data
Ordinary and Advanced Custom Routing share up to three saved profiles, each with 1–3 leading empty entry slots and a unique name of 1–32 characters. Advanced templates may append auxiliary outbounds. The types do not convert during editing. New Raw configurations are limited to three; existing older Raw records above the limit remain usable, with Add hidden.
Normal mode needs real server assets in the App. Automatic/source selection first seeks enough active, readable ordinary nodes for the requested entry count; successful cached latency ranks first, while untested or failed candidates remain eligible. Startup does not wait for tests. When the candidate count is insufficient, it can select one eligible complete provider configuration in the same scope. A fixed server uses that server. Raw JSON must contain its own actual proxy graph and does not borrow normal-mode nodes.
Node and Raw examples use reserved example domains and dummy IDs. Replace them with provider-supplied values. They are templates, not free working servers.
26.10.2 configuration additions
Optional Fragment is off by default. Each Smart or ordinary Custom route stores its own setting; see the defaults and template rules in Fragment routing.
LAN proxy sharing. The sharing switch and port apply on the next start/restart from the app; saving them does not reconnect an active VPN.
26.10.3 additions
Complete Remnawave subscriptions support object/array Xray responses and independent App/provider modes. Routing options add proxy/direct DNS fallback, managed sniffing and roundRobin/leastPing selection to ordinary configurations, plus limited probe settings for Advanced templates. Native resolver filters/cache overrides and sniffing exclusions remain Advanced/Raw-only. JSON hints cover Core v26.10.10 fields, including XDNS names/addrs, MASQUE WARP and TLS useSystemCA; Lua is outside the App editor/resource workflow.
26.10.4 additions
- Server dialing adds device-wide domain-resolution preferences and optional Happy Eyeballs for Smart, ordinary Custom and All VPN. Advanced templates, Raw JSON and provider configurations keep their own dialing boundaries.
- Subscriptions support a per-source User-Agent and compatible default. Invalid complete configurations are skipped individually; the selected mode must still receive usable entries. A non-JSON Remnawave response converts to an ordinary source only after confirmation.
- Apple backup can bind a selected file or iCloud Drive, with restore/overwrite choice for existing content. Protocol v1 retains explicit subscription UA; global dialing and display sorting stay device-local.
26.10.5 configuration additions
- Raw and provider graphs share portable VPN supplementation, with runtime-only tunnel DNS fallback when DNS servers are absent. Explicit DNS and rules remain user-owned.
- JSON hints cover XDrive templates/XMUX, MASQUE XMUX, XDNS TLS/QUIC and TLS/ECH/REALITY fields with object-specific context. Free-form and unknown fields remain intact.
- Managed FakeDNS uses IPv6 pool
2001:2::/48; explicit pools and the TUN interface address are unchanged. - Manual groups and positions are saved in optional backup-v1 fields. They do not create automatic connection scopes.
- Xray-core is updated to v26.10.21.
26.11.1 configuration additions
- Smart/ordinary Custom adds other DNS query handling, proxy by default; roundRobin falls back to a complete proxy chain.
- New Fragment defaults use FinalMask. Authored legacy Fragment/noise objects are retained; Freedom helpers in Advanced can use FinalMask.
- Native JSON entry points and contextual hints cover XDrive S3 and Freedom finalRules; hints do not imply support through ordinary subscription projection.
- Automatic/source selection can use one active complete provider configuration when healthy ordinary nodes are insufficient.
- Backup v1 adds matching-platform VPN settings; Core-scheduled geodata downloads remain App-managed.
- Xray-core is v26.10.29.
26.11.2 behavior and editor updates
- Connection selection no longer requires successful latency tests. Missing, failed or timed-out results do not trigger provider fallback by themselves; active asset, count, final-exit and permission checks remain.
- Personal Raw JSON is added from Servers → Add servers, alongside the separate ordinary-node JSON action. Raw and provider complete graphs retain their existing ownership and import formats.
- Routing, VPN Tunnel and Xray have independent main entries. JSON editors use full-page workspaces with a minimum height; ordinary/advanced route and Raw quotas are unchanged.
- Apple widgets/controls reuse the latest saved runtime input rather than compiling later App selections. Backup-v1 and the existing example JSON remain unchanged.
- Xray-core is v26.10.31.
26.11.3 DNS and server-list updates
- Managed DNS defaults use TCP. Explicit saved resolvers, templates and startup caches are not migrated.
- Advanced templates accept same-tag loopback auxiliaries; new templates proxy other DNS record types over TCP while preserving the original destination. Existing query policies stay intact.
- Raw/provider missing-DNS supplementation and server bootstrap DNS derive TCP resolver URLs from tunnel IPs; tunnel fields remain IP literals.
- Servers can batch-test the filtered node list. Automatic connection scope is chosen on Connect.
- Xray-core remains v26.10.31.
26.11.4 interface and desktop updates
- Setup shows two-step progress; Connect combines runtime and session metrics with stable disconnected placeholders.
- Shared pages simplify labels and spacing and follow system reduced-motion preferences. Linux uses system window decorations.
- Configuration import, selection, saved DNS and runtime-input ownership, and backup-v1 are unchanged. No saved configuration or cache is rewritten by this interface update.
- Xray-core is v26.11.9.