Open Settings → Data → Backup & restore. The empty views on Connect and Servers also offer Restore from backup, without leaving the current tab.

OneXray binds one backup file; new files default to OneXray-backup.json. Later successful backups replace that file. It does not keep version history, merge configurations, or synchronize configurations automatically in both directions.

Choose a destination

Platform	Destination
iPhone, iPad, macOS, macOS System Extension	iCloud Drive is the first option, using the OneXray Documents container. You can also choose an existing file or create one with the system picker. Both destinations use the same restore and automatic-backup settings.
Android	Create or select a file using the system file picker. Google Drive can be used when its document provider is available there. OneXray keeps permission to read and overwrite that file; it does not provide a separate Google sign-in.
Windows EXE, ZIP, MSIX	Select a folder already synchronized by OneDrive. OneXray writes an ordinary file; OneDrive handles account sign-in and cloud synchronization.

Linux does not expose this feature. A successful write means the storage provider accepted the file, not that it has finished uploading to the cloud. Make sure the file is readable on another device before relying on it. Provider or connection failures can interrupt writes, so do not assume that every provider guarantees an atomic replacement.

When you choose a destination, OneXray checks whether the file has content. An empty file receives the first backup immediately, even with automatic backup off. For a nonempty file, choose Restore or Overwrite backup; cancelling keeps the previous binding and file. Restore validates the file and shows a replacement preview. Overwrite replaces the existing content without requiring it to be a valid backup. An unreadable file is reported as an error and is not treated as empty.

On Apple, use Switch to local backup to choose or create a file, or Switch to cloud backup for iCloud Drive. On iOS, creating a file asks for its destination folder. Keep a selected file outside OneXray’s app data so it survives removal of the app. After reinstalling, select the existing file again. Cancelling a switch keeps the current destination; unbinding or clearing app data does not delete the external file.

Sensitive data

The backup is not encrypted. It can contain server credentials, subscription URLs, Age private keys, and subscription HWID values. Base64-encoded configuration text is not encryption. Keep the file private, restrict access to its destination, and never publish it as a share link or paste it into an AI conversation. Cloud-storage providers apply their own security and privacy policies; the file is not uploaded to a OneXray server.

What is included

Included	Not included
Manually added nodes and complete Raw JSON source	Subscription node caches, local edits to those cached nodes, test results and favorites
Subscription names, URLs, explicit User-Agent, Age keys, HWID and its enabled state	Downloaded files, GeoData contents and indexes, logs, certificates, or external key files
Ordinary and advanced Custom Routing names, types, and source configurations	The current server/route/Raw selection, expert-mode state, and the app’s final-exit selection
Smart Routing options and matching platform VPN settings	Physical outbound-interface names, device permissions, API/automation authorizations and app preferences
Custom GeoData file names, types, and HTTPS source URLs, including pending downloads	Default GeoData files and their source records

Raw JSON retains its own outbound definitions. Excluding the app’s final-exit selection does not remove nodes from a complete Raw configuration. Independently referenced files must be prepared on the receiving device.

Automatic and manual backup

Automatic backup is on by default. Choosing an empty destination or confirming overwrite writes the first backup regardless of this switch. Choosing restore leaves the source file unchanged and starts the next backup interval from binding time; “last successful write on this device” changes only after an actual write. The switch controls later automatic writes; manual backup remains available when it is off.

The backup interval is independent of GeoData: choose 1, 3, or 7 days, with 3 days as the default. The app checks whether a backup is due at startup, on return to the foreground, and during periodic checks while it runs. This is not a guaranteed operating-system background schedule while the app is suspended or closed, and it does not require VPN to be connected.

Automatic failures are shown on the backup page and do not change VPN state. Manual retry is available. Turning off automatic backup stops future automatic writes; it does not remove the existing file.

Restore

1. Select the destination and read the backup. A cloud-only file may first need to be downloaded by its storage provider.
2. Review the preview and confirm replacement. Restore replaces the managed connection configurations; it does not merge them. OneXray stops VPN before applying the restore. If stopping fails, existing configurations remain unchanged.
3. Return to the app. Current selections reset to normal mode with automatic selection and Smart Routing; VPN does not start automatically. Matching platform settings restore when present; otherwise local settings remain. App preferences are retained.
4. Update restored subscriptions to fetch their nodes. Manually added nodes and Raw JSON are already in the backup. Restore does not automatically refresh subscriptions or wait for node tests.

Once the backup file can be read, restoring configuration records does not require internet access. It does not guarantee that every restored configuration can immediately connect.

When GeoData cannot be downloaded

Valid local custom data with the same file name, type, and source URL is reused. Other custom sources are restored as pending downloads, without blocking the restore or entry to the home page. A conflicting source with the same name is shown before replacement. Default routing data uses the device’s valid existing or bundled files.

A configuration that needs a missing file reports that dependency instead of dropping its rules, silently sending traffic directly, or downloading during VPN startup. Use another working configuration if needed, then download the missing data from GeoData. Automatic GeoData updates still require a connected VPN. Pending data cannot supply autocomplete categories until it is downloaded and indexed.

Backup format and sharing

The backup is a version-1 JSON document identified by format: "onexray-backup", not an old ZIP backup. Restore accepts files up to 64 MiB. Use Backup & restore, not node, Custom Routing, or Raw JSON import, to read it.

For individual configurations, use sharing and import. Unlike subscription sharing, backup intentionally retains Age private keys and HWID for restoration. AI-generated configurations should use the documented configuration formats, not a fabricated backup document.

Backup fields and compatibility

Protocol v1 also retains subscription panel/mode and supported Smart DNS/sniffing/selection settings. Existing backups missing these use Generic/App-managed sources and the old routing defaults. Complete provider and derived outbound caches are not backed up; refresh after restoring. Personal Raw copies are ordinary backed-up assets. Unknown fields are ignored and omitted on re-export; format, version, required sections, known types and explicit enums are still checked. Runtime probes and retired region data are not backed up. Ordinary DNS timeout/cache/filter/stale/parallel fields and sniffing exclusions from old internal data are retired; external ordinary JSON import remains strict.

Protocol v1 retains an explicit per-subscription User-Agent. If absent, downloads use the receiving device’s compatible default. Server display order remains device-local; server dialing is included in the matching platform section.

Protocol v1 also retains named manual groups (including empty groups), group order, node membership and within-group positions. Older backups without these optional fields restore manual nodes as Ungrouped in their original order. Manual groups organize assets, not connection selection; restoring does not create group-based automatic connection.

Platform-specific VPN settings

Protocol v1 can include platformSettings with separate ios, macos, android, windows and linux keys. A backup writes the current platform’s migratable VPN settings; restore reads and validates only the matching key. iOS and macOS do not match each other; OneXraySE uses macos, and all Windows editions use windows. This does not add a Linux backup screen.

The matching section includes IPv6, tunnel DNS, server dialing, LAN sharing, logging preferences and that platform’s VPN policy. Android includes the access mode and both included/excluded package-name lists, retaining entries for apps not currently installed. Other platforms’ sections do not alter local settings. Missing sections or omitted settings keep the receiving device’s current values; a malformed matching section is reported before replacement.

Physical outbound-interface names, system permissions, API/automation authorizations, appearance preferences and the backup destination remain device-local. Confirmed restoration applies supported matching settings with the connection assets and stops VPN first; it does not automatically reconnect.