Android lockdown
For blocking across a whole VPN process crash, set this app as Always-on VPN and enable Block connections without VPN in Android settings. The OS controls this policy and can prevent in-app Stop.
Android Always-on VPN ↗flutter_vless 1.1.8
Run the included Flutter example, connect with your own link, and see traffic move. Then try sending it down a different path.
Quick start
Choose where the app will run, then how it should carry traffic. Start with one working profile.
Send device traffic through an OS tunnel.
Run a local proxy for apps that use it.
On Windows, install Flutter and Android Studio on your PC. Open Device Manager in Android Studio and start an emulator, or enable USB debugging on your phone and accept the prompt after connecting it. Install your phone’s Windows USB driver if needed.
flutter doctor --android-licenses
flutter doctor -v
flutter devicesRun these commands. Replace DEVICE_ID with the Android ID from flutter devices.
git clone --filter=blob:none --no-checkout https://github.com/XIIIFOX/flutter_vless.git
git -C flutter_vless checkout --detach 49369d94a11716a19295b76dc7296409748b5a7f
cd flutter_vless/example
flutter pub get
flutter run -d DEVICE_IDCopy a working share link to the clipboard on the device running Example. Tap Import (clipboard). Get a connection link if you don’t have one yet. Leave VPN routing off for the first run.
Before connecting, record your public IP at tfox.dev/ip. To see the VPN exit on this page, remove tfox.dev if it appears in Routing / Rules → Bypass domains, then tap Apply rules.
Switch the mode control until it reads VPN Mode, then tap Connect. Accept Android’s VPN permission prompt. When the status says CONNECTED, reopen tfox.dev/ip in a fresh tab and compare it with the IP you recorded before connecting. Tap Disconnect to finish.
Switch the mode control until it reads Proxy Only, then tap Connect. A profile generated from a share link provides a SOCKS5 listener at 127.0.0.1:10807 on this device. A custom JSON profile may use a different port.
Use a SOCKS5-aware app on Android to make a request through that listener, or run the ADB check below.
For a direct SOCKS test from a computer, forward the Android listener over ADB to local port 10807, then make a request. Read the ip field in the JSON response. If you have multiple Android devices, add -s DEVICE_ID after each adb. Run this in PowerShell on Windows. On macOS or Linux, replace curl.exe with curl.
adb forward tcp:10807 tcp:10807
curl.exe --proxy socks5h://127.0.0.1:10807 https://tfox.dev/ip/api
adb forward --remove tcp:10807Tap Disconnect when you’re done.
Run this in PowerShell. The project’s installer downloads and verifies the Windows Xray runtime. The Example checkout already includes the tunnel helpers.
git clone --filter=blob:none --no-checkout https://github.com/XIIIFOX/flutter_vless.git
git -C flutter_vless checkout --detach 49369d94a11716a19295b76dc7296409748b5a7f
cd flutter_vless
py -3 tool/windows/install_published_runtime.py --directory example/windows/xray
cd exampleFrom example/, build the app and copy its runtime files next to the executable.
flutter pub get
flutter build windows --release
$bundle = "build/windows/x64/runner/Release"
New-Item -ItemType Directory -Force "$bundle/xray" | Out-Null
Copy-Item windows/xray/* "$bundle/xray"Open PowerShell as Administrator. Change to the same example/ folder and run:
From your regular PowerShell in example/, run:
& ".\build\windows\x64\runner\Release\flutter_vless_example.exe"Copy a working share link to the clipboard on the device running Example. Tap Import (clipboard). Get a connection link if you don’t have one yet. Leave VPN routing off for the first run.
Before connecting, record your public IP at tfox.dev/ip. To see the VPN exit on this page, remove tfox.dev if it appears in Routing / Rules → Bypass domains, then tap Apply rules.
Switch the mode control until it reads VPN Mode, then tap Connect. Allow the Windows permission prompt if shown. When the status says CONNECTED, reopen tfox.dev/ip in a fresh tab and compare it with the IP you recorded before connecting. Tap Disconnect to finish.
Switch the mode control until it reads Proxy Only, then tap Connect. A profile generated from a share link provides a SOCKS5 listener at 127.0.0.1:10807 on this device. A custom JSON profile may use a different port.
The plugin applies Windows system proxy settings. This command tests the local proxy explicitly and returns the exit address in the ip field.
curl.exe --proxy socks5h://127.0.0.1:10807 https://tfox.dev/ip/apiTap Disconnect when you’re done.
Run this on your Mac. Work in the Runner.xcworkspace that opens.
git clone --filter=blob:none --no-checkout https://github.com/XIIIFOX/flutter_vless.git
git -C flutter_vless checkout --detach 49369d94a11716a19295b76dc7296409748b5a7f
cd flutter_vless/example
flutter pub get
../tool/prepare_apple_swiftpm.sh
open ios/Runner.xcworkspaceConnect and trust your iPhone, enable Developer Mode if prompted, and select it as the Runner destination.
Set the same Apple Team for Runner, XrayTunnel and VlessControls. Confirm the App Group and Network Extension capabilities. Then press Run in Xcode.
Use a unique base bundle ID and matching extension IDs ending in .XrayTunnel and .VlessControls. Register your App Group, then update entitlements, the example’s Info.plist files and both initialization calls in lib/main.dart. On iOS, keep the shared Keychain group consistent too. Check the platform guide.
Replace DEVICE_ID with the iPhone ID from flutter devices.
flutter devices
flutter run -d DEVICE_IDCopy a working share link to the clipboard on the device running Example. Tap Import (clipboard). Get a connection link if you don’t have one yet. Leave VPN routing off for the first run.
Before connecting, record your public IP at tfox.dev/ip. To see the VPN exit on this page, remove tfox.dev if it appears in Routing / Rules → Bypass domains, then tap Apply rules.
Switch the mode control until it reads VPN Mode, then tap Connect. Approve adding the VPN configuration when iOS asks. When the status says CONNECTED, reopen tfox.dev/ip in a fresh tab and compare it with the IP you recorded before connecting. Tap Disconnect to finish.
Switch the mode control until it reads Proxy Only, then tap Connect. A profile generated from a share link provides a SOCKS5 listener at 127.0.0.1:10807 on this device. A custom JSON profile may use a different port.
Selecting this mode starts Xray in the app without installing a tunnel. The Example’s build still includes its extension targets.
In a SOCKS5-aware iPhone app that lets you select its proxy, point it at the listener above and open tfox.dev/ip to check the exit address.
Tap Disconnect when you’re done.
Run this on your Mac. Work in the Runner.xcworkspace that opens.
git clone --filter=blob:none --no-checkout https://github.com/XIIIFOX/flutter_vless.git
git -C flutter_vless checkout --detach 49369d94a11716a19295b76dc7296409748b5a7f
cd flutter_vless/example
flutter pub get
../tool/prepare_apple_swiftpm.sh
open macos/Runner.xcworkspaceSelect My Mac as the Runner destination.
Set the same Apple Team for Runner, XrayTunnel and VlessControls. Confirm the App Group and Network Extension capabilities. Then press Run in Xcode.
Use a unique base bundle ID and matching extension IDs ending in .XrayTunnel and .VlessControls. Register your App Group, then update entitlements, the example’s Info.plist files and both initialization calls in lib/main.dart. On iOS, keep the shared Keychain group consistent too. Check the platform guide.
flutter run -d macosCopy a working share link to the clipboard on the device running Example. Tap Import (clipboard). Get a connection link if you don’t have one yet. Leave VPN routing off for the first run.
Before connecting, record your public IP at tfox.dev/ip. To see the VPN exit on this page, remove tfox.dev if it appears in Routing / Rules → Bypass domains, then tap Apply rules.
Switch the mode control until it reads VPN Mode, then tap Connect. Approve adding the VPN configuration when macOS asks. When the status says CONNECTED, reopen tfox.dev/ip in a fresh tab and compare it with the IP you recorded before connecting. Tap Disconnect to finish.
Switch the mode control until it reads Proxy Only, then tap Connect. A profile generated from a share link provides a SOCKS5 listener at 127.0.0.1:10807 on this device. A custom JSON profile may use a different port.
Make a request through the local proxy from a separate Terminal window and read the ip field.
curl --proxy socks5h://127.0.0.1:10807 https://tfox.dev/ip/apiTap Disconnect when you’re done.
Compare browser, app, and device traffic before you choose a mode.
Commands check out a 1.1.8 revision from GitHub main so the Example and Dart API match this guide.
Proxy & VPN
Send traffic from a browser, from the networking clients in your own app, or from the device through its OS tunnel.
Follow Quick start with a working share link. The default generated SOCKS5 listener is 127.0.0.1:10807. Keep it on loopback and use the actual address, port, and authentication for a custom configuration.
On the same desktop, open Firefox settings and search for proxy. In its connection settings, choose Manual proxy configuration. Set SOCKS Host to 127.0.0.1, port 10807, and select SOCKS v5. Enable proxy DNS if you want the browser to resolve destinations through SOCKS and the option is available. Firefox connection settings
Open tfox.dev/ip in a fresh browser window and compare it with the IP from before you connected. Use a profile that routes tfox.dev through the proxy. Restore the previous browser settings when finished. On Windows, use a baseline from before Proxy Only started because it also configures the OS proxy.
In a native Flutter app, start the listener with an initialized FlutterVless controller and a working link. Wait for the connected status before sending requests.
import 'package:flutter_vless/flutter_vless.dart';
Future<void> startAppProxy(FlutterVless vless, String shareLink) async {
final profile = XrayProfile.build((draft) {
final node = draft.addNode(ProxyNode.fromLink(shareLink));
draft.setDefaultRoute(RouteTarget.node(node));
});
await vless.startVless(
remark: 'App proxy',
config: profile.toCoreJson(),
proxyOnly: true,
);
}Run the command below to add a SOCKS5 adapter. Then create one proxied HTTP client after the connection is ready and pass it to your app’s API and download code. Reuse it for requests. Close it on disconnect, await stopVless(), and surface failures to the user if the proxy is unavailable.
flutter pub add socks5_proxy:2.1.2import 'dart:convert';
import 'dart:io';
import 'package:socks5_proxy/socks_client.dart';
HttpClient makeProxiedClient() {
final client = HttpClient();
client.findProxy = (_) => 'DIRECT'; // SOCKS is set by the connection factory below.
SocksTCPClient.assignToHttpClient(client, [
ProxySettings(InternetAddress.loopbackIPv4, 10807),
]);
return client;
}
Future<String> readExitIp(HttpClient client) async {
final request = await client.getUrl(Uri.https('tfox.dev', '/ip/api'));
final response = await request.close();
if (response.statusCode != HttpStatus.ok) {
await response.drain();
throw HttpException('Check IP request failed.');
}
final data = jsonDecode(await utf8.decodeStream(response));
if (data is! Map || data['ip'] is! String) {
throw const FormatException('Check IP returned an invalid response.');
}
return data['ip'] as String;
}For package:http, pass this client to IOClient. Configure separate networking stacks explicitly and test each one before calling the whole app proxied. A native dart:io client works on supported native targets. A web app or WebView has its own networking stack.
Routing
Use routing when one destination should go directly and the rest should go through your connected profile.
tfox.devDirectUse a single share link in the regular Example. If tfox.dev is already in the bypass list, remove it while disconnected and apply the rules. Open tfox.dev/ip once while disconnected and once while connected. Note the two IPs if your exit has a different public IP. Then disconnect.
Open the gear button labeled Routing / Rules. Under Bypass domains (one per line), replace the entries for this test with the domain below. Tap Apply rules and go back.
tfox.devOpen tfox.dev/ip again in a fresh browser session. It should show your direct IP. To undo the test, disconnect, use Clear and Apply rules, then reconnect.
The Example adds a domain rule ahead of the imported rules. It points at an outbound tagged direct using Xray’s freedom protocol. Share links parsed by the plugin already provide that outbound. For custom JSON, check the tag and rule order before reusing the helper.
With the public 1.1.8 API you can build the same route directly and pass profile.toCoreJson() to startVless.
import 'package:flutter_vless/flutter_vless.dart';
XrayProfile buildSplitRoute(String link) {
return XrayProfile.build((draft) {
final proxy = draft.addNode(ProxyNode.fromLink(link));
draft.addRule(RouteRule.domains(
['domain:example.org'],
to: RouteTarget.direct(),
));
draft.setDefaultRoute(RouteTarget.node(proxy));
});
}When your Android VPN policy allows excluding an app, disconnect, open Routing / Rules and add its package name under Bypass apps (package names, one per line). Apply the rules, reconnect, and verify that app and a second app separately.
Balancer
Use a balancer when you have two or more working profiles and want Xray to choose an exit for new connections.
Finish your platform setup in Quick start. Then stop the regular app and run this from example/. If Flutter asks for a target, choose your device.
flutter run -t lib/balancer_example.dartUse the same Windows quick start. Replace its build command with the line below, then copy the runtime files and launch the executable as before.
flutter build windows --release -t lib/balancer_example.dartPut two distinct share links on separate lines on the device clipboard. Tap Import (clipboard) and check that Configuration (JSON) shows 2 balancer nodes. A supported subscription with two or more profiles works too.
Choose VPN Mode or Proxy Only, then tap Connect. The default strategy is roundRobin. Test new connections to a destination using the balancer, with exits that have different public IPs. Reloading a tab can reuse an existing connection.
Run the same command twice and compare the ip fields. Make sure your profile sends tfox.dev through the balancer. On Windows, use curl.exe. In VPN mode use the command without the --proxy argument.
curl --proxy socks5h://127.0.0.1:10807 https://tfox.dev/ip/apiUse the public 1.1.8 profile API to add two nodes, group them and set the group as the default route. Pass real share links as arguments.
import 'package:flutter_vless/flutter_vless.dart';
XrayProfile buildBalancer(String firstLink, String secondLink) {
return XrayProfile.build((draft) {
final first = draft.addNode(ProxyNode.fromLink(firstLink));
final second = draft.addNode(ProxyNode.fromLink(secondLink));
final group = draft.addGroup(
nodes: [first, second],
strategy: const BalanceStrategy.roundRobin(),
);
draft.setDefaultRoute(RouteTarget.group(group));
});
}After initializing your FlutterVless controller and getting VPN permission, start it with the profile’s Core JSON. For Proxy Only, pass proxyOnly: true and skip the VPN permission step.
final profile = buildBalancer(firstLink, secondLink);
await controller.startVless(
remark: 'Two servers',
config: profile.toCoreJson(),
);Start with roundRobin to take turns. Use random to pick an exit at random. Try leastPing or leastLoad when you have a probe URL and want measured selection. Give the probe time to see a healthy exit before sending traffic.
Kill switch
If a worker fails after the VPN has taken over, the kill switch keeps captured traffic from silently switching to a direct route.
Run the Example and open Plugin options → Protection Options to see the Kill Switch status. Protection is mandatory for VPN mode in 1.1.8 and active once the tunnel is established. Proxy Only serves configured clients without device-wide protection.
Use a dedicated test profile. Confirm a fresh request to a destination routed through it, then temporarily make its test server unreachable while the device stays online. Make another fresh request. It may fail or wait for recovery, but it should never take the direct route just because the tunnel stopped forwarding. Intentional direct rules still apply.
Check that a fresh request works again when the connection recovers. Tap Disconnect and verify ordinary connectivity returns. An active Android Always-on policy can require ending the session in system settings.
For blocking across a whole VPN process crash, set this app as Always-on VPN and enable Block connections without VPN in Android settings. The OS controls this policy and can prevent in-app Stop.
Android Always-on VPN ↗On iOS and macOS, workers can recover inside a running Packet Tunnel. On Demand can request a relaunch if the provider terminates. The OS decides when to relaunch, so continuous capture after a full provider crash is not guaranteed.
Apple recovery behavior ↗The Windows Filtering Platform barrier can remain after the app closes or crashes. Reopen Example as Administrator and explicitly disconnect to release the barrier.
Windows protection details ↗In Dart, ProtectionOptions(killSwitch: KillSwitchPolicy.required) expresses the requirement. Worker retry policy is configured separately in Options.
Plugin options
Start with a working VPN profile. Change one setting at a time and check it on the device that will use it.
Disconnect the current session, then open Plugin options in the Example. Choose a small change from the use cases below.
Tap Apply options. Reconnect your known-good profile so the new session uses the selected settings. System controls need a supported surface and an authorized VPN profile.
Watch a reconnect, try the quick control, or open VPN Diagnostics while you reproduce a connection problem. Use getCapabilities() in your own app to show only the controls the loaded backend supports.
Use Quick Access Options for an Android Quick Settings tile, a macOS menu bar item, a Windows tray control, or an Apple Control Center control on supported versions with a configured extension. Desktop tray and menu bar controls need the app to stay running.
Apple control setup ↗Use Notification Options to choose a bundled icon and an action like Open app or Disconnect. Choosing no action keeps the required foreground notification visible.
Use Auto Reconnect for native worker recovery. A retry limit of 0 means unlimited attempts. If retries end, protection stays in place until Stop. Apple On Demand governs OS relaunch separately.
Platform protectionOn a backend that supports it, use AlwaysOnMode.requireEnabled to require the system’s Always-on setting. Android users or administrators turn it on. The lockdown setting is a separate OS choice.
Use Diagnostics Options to bound privacy-filtered records by bytes and lines. To see exit selections in a balancer test, enable Record balancer selections when the backend offers it, reconnect in VPN mode, then inspect VPN Diagnostics.
Balancer walkthroughUse this preset on a target with a supported quick control and any required host setup. Otherwise leave quick access disabled. Initialize the returned controller with your platform identifiers, then start an authorized VPN profile.
import 'package:flutter_vless/flutter_vless.dart';
const vpnOptions = VlessOptions(
quickAccess: QuickAccessOptions(
enabled: true,
label: 'Work VPN',
action: VlessSystemAction.toggle,
),
protection: ProtectionOptions(killSwitch: KillSwitchPolicy.required),
diagnostics: DiagnosticsOptions(maxBytes: 16 * 1024, maxLines: 60),
);
FlutterVless makeController(void Function(VlessStatus) onStatusChanged) {
return FlutterVless(
onStatusChanged: onStatusChanged,
options: vpnOptions,
);
}Use VlessOptions.fromMap(options.toMap()) to round-trip non-secret settings. Keep connection links and Xray configurations out of these preferences. See the full Options and system controls reference.
Connection links
A share link tells the client which server to call and how to sign in. Keep it private, like a password.
Already have a provider or server admin? Ask for a working vless:// share link. Go straight to step 3.
On a Linux VPS, install Xray from Project X’s official instructions. Follow its VLESS server guide to set up a domain, a TLS certificate, and an authorized user UUID. Make the configured inbound port reachable and confirm the Xray service is running.
With the official systemd install, run this on your VPS after saving your server configuration. The restart runs only if Xray accepts the configuration.
sudo /usr/local/bin/xray run -test -c /usr/local/etc/xray/config.json &&
sudo systemctl restart xray
sudo systemctl --no-pager status xrayUse your server panel’s share option, or create a client profile with the same host, port, UUID, transport and security settings. Export it as a vless:// link. For REALITY, match the server’s client-side parameters, including its public key. Keep server private keys on the server.
Copy the link into a client such as v2rayNG on Android or v2rayN on Windows. Connect and make a real HTTPS request through the profile. If it fails, check the host, port and security settings before moving on.
Disconnect the other client. Copy the link to the clipboard of the device running Example, tap Import (clipboard), and follow Quick start.
Codex / Claude Code
Open Codex or Claude Code in your Flutter project, choose a platform and use case, and paste the prompt below.
Help me integrate flutter_vless 1.1.8 into the Flutter app in this workspace.
Read the app's pubspec.yaml, networking code, supported platforms, and local project instructions first. Use the public Dart API and Example from this revision:
https://github.com/XIIIFOX/flutter_vless/tree/49369d94a11716a19295b76dc7296409748b5a7f
Read the Example README, doc/getting-started.md, and the target platform guide. Use https://tfox.dev/flutter-vless/docs/ for the walkthrough.
My target platform: [Android, iOS, macOS, or Windows]
My use case: [app-only proxy, device VPN, split routing, or balancing]
First help me verify a single working link in the bundled example. Then make the smallest working integration in this app with Connect, Disconnect, and status handling. Use a local test input for the link. Keep credentials and raw configs out of source control and logs.
For app-only proxy, wire the clients that should use it to the local SOCKS5 listener. List the separate network stacks and identify which are covered. Surface a failed proxy connection rather than retrying directly. For device VPN, set up OS permissions and use the platform's supported protection. Explain any signing or OS steps I need to complete.
If I selected routing or balancing, use the typed XrayProfile API and test a fresh request through each intended route. For Options, query getCapabilities() and offer only supported controls.
Run analysis and available tests. Verify a real request and Disconnect on a supported test device if available. Tell me what passed, what still needs a device, and which files changed.Replace the two bracketed lines with your choices. Keep your real share link out of the prompt and supply it locally when you test.
FAQ
Start here when you’re choosing a mode or checking your first connection.
Xray is the networking engine. It runs on your server and the client uses it to connect and move traffic. flutter_vless gives a Flutter app a Dart API for importing profiles and starting or stopping the client runtime. The Example is a small Flutter app that already wires these pieces together.
Choose VPN to send device traffic into the OS tunnel and approve the platform prompt. Choose Proxy to run a local listener and use it from a compatible app. Proxy-aware apps can use the local listener. On Windows the example also applies system proxy settings, which some apps ignore. See browser and app setup.
Start with one working vless:// share link. The regular Example can also import supported protocols, full Xray JSON, and the first supported profile from a subscription. Use the Balancer Example to group multiple links. Check supported formats.
Use macOS with Xcode to build and sign the iOS Example. Windows can build the Android Example and run it on an emulator or on a phone over USB. Choose a real signed iPhone for iOS VPN testing.
First use Delay or make a fresh request through the right mode. Proxy Only needs a proxy-aware app or a command using the local listener. If traffic still fails, try the same profile in another client and check that the server is reachable. Open the troubleshooting guide.
Add the dependency to your own Flutter app and carry over only the platform setup you need. Use the current Example as a reference for starting and stopping a session and handling status. Integration guide · Dart API reference.