These configuration contracts describe OneXray 26.11.1. 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-core v1.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.

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 healthy ordinary nodes for the requested entry count; when 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.

The current contract was reviewed on 2026-10-31 against App 26.11.1 source 565b5f3121862a899e2ed8e596d229e91af22d4c, compared with v26.10.5 (73c1cb33fb755d8da324064225bff17734e590f6). The example manifest keeps its earlier native-validation provenance; this review does not rerun those examples.

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.