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

OneXray keeps one OneXray-backup.json file. Each successful backup replaces the previous contents. This is not version history, a merge tool, or automatic two-way configuration synchronization.

Choose a destination

Platform	Destination
iPhone, iPad, macOS, macOS System Extension	The OneXray iCloud Documents container. Enable iCloud Drive for the app and use the same Apple account on devices that need the same file.
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.

Selecting or reading a destination does not authorize overwriting it. Review the sensitive-data warning and confirm before the first backup. You can restore an existing file before giving permission to replace it. Unbinding a destination or clearing app data does not delete the external backup 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, locations, and favorites
Subscription names, URLs, 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	VPN Tunnel settings, device permissions, platform policy, 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, but cannot write until a destination is confirmed. If enabled, confirmation creates the first backup. You can turn it off and use manual backup instead.

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 are reset to normal mode with automatic selection and Smart Routing; VPN does not start automatically. Target-device tunnel settings and 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.