Android system VPN

Open Advanced > VPN Tunnel > Android system VPN.

Choose a mode

The include and exclude lists are stored separately. Switching modes does not overwrite the other list.

Select applications

Open the application picker, search by app or package name, and select entries. App icons help distinguish similar names. The installed-app list is used locally for this feature and is not uploaded to OneXray.

Only selected apps requires at least one installed app. Removing every app from an allow-list does not silently mean “all apps”.

Save to apply the list. If VPN is active, applying tunnel changes requires reconnecting. Per-app selection decides which applications reach the tunnel; Smart/Custom Routing then handles the traffic inside it.

Permissions and system controls

After Setup, entering the main interface checks VPN status and requests missing permissions. Android 17 and later also require the applicable local-network permission. Declining does not prevent browsing the app; Connect lets you retry. Returning to the foreground refreshes status without repeatedly opening authorization dialogs.

The VPN can be controlled through OneXray, its foreground notification, the Quick Settings tile, and app-icon shortcuts. Scanning QR codes requests camera access separately, only when used.

External automation

Open External automation from this page, enable Allow external automation, and copy the token. It is off by default and supports only starting and stopping VPN, not server selection, subscription updates, or state-query broadcasts. This is separate from the desktop HTTP API.

Complete VPN and applicable local-network authorization in OneXray, then connect normally once. Automation reuses the most recently generated complete startup configuration; it does not recompile the current database selection. After changing servers or routing, connect from the app first. The most recently generated configuration is not necessarily a previously successful connection.

Broadcast parameters

Specify both Package and Class. START and STOP require the same string token; this is an Intent Extra, not an HTTP header.

Target: Broadcast Receiver
Package: net.yuandev.onexray
Class: net.yuandev.onexray.automation.VpnAutomationReceiver
START Action: net.yuandev.onexray.action.START_VPN
STOP Action: net.yuandev.onexray.action.STOP_VPN
Extra key: token
Extra type: String

Automate

Add a Broadcast send block with the Package and Receiver class above. Switch Action to expression mode (fx) and enter the quoted action, for example:

"net.yuandev.onexray.action.START_VPN"

Set Extras to a dictionary, replacing YOUR_TOKEN with the complete copied token:

{"token": "YOUR_TOKEN"}

Leave other fields empty. A preceding Delay block lets you return Home before delivery. Automate 1.53.2 was tested on Android API 37 for background START/STOP, incorrect tokens, and rejection after token reset. Other Android releases and manufacturer power policies require separate testing. Official Automate reference.

Tasker

Use Send Intent with Target Broadcast Receiver and the Action, Package, and Class above. Set Extra to token:YOUR_TOKEN, or store the token in a variable and use token:%OneXrayToken. Add no quotes or spaces; leave other fields empty. The ox_ prefix keeps the token from being interpreted as a number. Tasker was not device-tested in this validation; these instructions follow its official documentation.

MacroDroid

Use Send Intent, choose Broadcast, and enter the Action, Package, and Class above. Add a String Extra named token, using the copied value or a stored string variable inserted through the variable picker. Leave other fields empty. MacroDroid was not device-tested in this validation; field labels may vary by version, so verify the broadcast target and String type.

Tokens and failures

• Disabling preserves the token; re-enabling can reuse existing tasks. Resetting requires updating every task. Neither operation stops the current VPN.
• The token belongs to this device and is excluded from connection configurations and backups. Clearing app data or uninstalling requires new authorization; restoring a connection backup preserves this device’s authorization. Remove tokens before sharing flows. Ordinary automation variables are not a secure credential vault.
• Repeated START does not launch another core. STOP can cancel a pending start and does not require startup files or startup permissions.
• Missing configuration, permissions, or resources do not trigger downloads or automatically open OneXray. Read the failure notification and tap it to resolve the problem. If notifications are disabled, check system notification settings and the app’s state.
• Disabled automation and missing, incorrect, or non-string tokens are silently ignored. “Sent” is not a connection acknowledgement: check the VPN notification, widget, or app.
• Data clearing/restoration blocks START but still accepts authenticated STOP. Force-stop, a locked device after reboot, Doze, manufacturer background restrictions, or another always-on/lockdown VPN may affect execution. This feature does not bypass them.