Forem: Amir Ziari

💻 Flutter V2Ray Client Desktop Plugin — V2Ray/Xray & Sing-Box VPN for Windows, macOS, Linux

Amir Ziari — Tue, 11 Nov 2025 20:46:11 +0000

🧩 Following the success of flutter_v2ray_client (mobile), I'm excited to introduce the Desktop Edition — a premium Flutter plugin that brings V2Ray, Xray, and Sing-Box VPN/TUN capabilities to Windows, macOS, and Linux.

Ideal for developers and companies building cross-platform VPN or proxy tools.

🎥 Quick Youtube Video Demo

Watch on YouTube

💎 Premium Highlights

🔒 2-Year Guarantee — Free updates & maintenance

💬 Priority Support — Fast Telegram support for all premium users

🚀 Advanced Features — Real-time stats, VPN/TUN mode, delay tests

⚠️ Need help? Contact @AmirZrDevv or open a GitHub issue. Support replies within 24 hours.

🖥️ Overview

flutter_v2ray_client_desktop lets you run V2Ray/Xray and Sing-Box (VPN/TUN) with a unified Flutter API.

It includes system proxy management, URL parsing, and real-time network stats — all in pure Dart.

Component	Version
Xray Core	`25.10.15`
Sing-Box	`1.12.10`

With each Xray and Sing-Box update, you will receive new updates.

🔎 Key Use Cases

Build a cross‑platform VPN client with TUN/VPN and system proxy modes.
Parse vmess/vless/trojan/ss/socks links to valid Xray configs.
Show live bandwidth, totals, and uptime in your UI.
Run delay tests (HTTP/ICMP/TCP) to auto‑pick the fastest server.

✨ Core Features

🔌 Connection Modes: proxy, systemProxy, vpn
📊 Live Status: speed, totals, uptime, connection state
⚙️ System Proxy Control: Windows/macOS/Linux
🔒 VPN/TUN with Sing-Box
⏱️ Server Delay Test: HTTP / ICMP / TCP
🔗 Share-Link Parser: vmess/vless/trojan/ss/socks → Xray JSON

🌐 Platform Setup

Platform	Binary Location	Notes
Windows	`windows/resources/`	Run app as Administrator for VPN mode
macOS	`macos/Resources/`	Requires `sudoPassword` at runtime for VPN
Linux	`linux/resources/`	Requires `sudoPassword` at runtime for VPN

⚠️ VPN mode requires admin/root privileges.

📦 Installation

dependencies:
  flutter:
    sdk: flutter
  flutter_v2ray_client_desktop:
    git:
      url: # Replace with the actual path to your local flutter_v2ray_client_desktop directory
    # Example (uncomment and modify as needed):
    # path: /path/to/your/local/flutter_v2ray_client_desktop

Run flutter pub get.

🚀 Quick Start

import 'package:flutter_v2ray_client_desktop/flutter_v2ray_client_desktop.dart';

final client = FlutterV2rayClientDesktop(
  logListener: print,
  statusListener: print,
);

await client.startV2Ray(
  config: jsonConfig,
  connectionType: ConnectionType.systemProxy,
);

Stop it:

await client.stopV2Ray();

🧠 Logs & Status

logListener(String log)

→ Receives raw logs: "[Xray]...", "[sing-box]...".

statusListener(V2rayStatus status)

→ Fires every second:

V2rayStatus(
  state: ConnectionState.connected,
  duration: 0:02:15,
  download: 12456,
  upload: 2345,
  totalDownload: 3456789,
  totalUpload: 456789,
)

🧩 Parser API (`V2rayParser`)

Convert links into full configs:

final parser = V2rayParser();
await parser.parse('vmess://...');

final fullJson = parser.json();
await client.startV2Ray(
  config: fullJson,
  connectionType: ConnectionType.systemProxy,
);

Supported protocols:

vmess://, vless://, trojan://, ss://, socks://

🧰 API Reference (Summary)

Type	Description
`ConnectionType`	`proxy`, `systemProxy`, `vpn`
`DelayType`	`http`, `icmp`, `tcp`
`V2rayStatus`	Tracks speed, totals, duration
`FlutterV2rayClientDesktop`	Main controller

❓ FAQ

Does VPN/TUN work on all platforms? Yes. TUN mode uses Sing‑Box. It requires admin/root privileges.
How do I disable the system proxy when stopping? stopV2Ray() automatically disables the system proxy or stops VPN depending on ConnectionType (see FlutterV2rayClientDesktop.stopV2Ray() in lib/flutter_v2ray_client_desktop.dart).
Can I query versions at runtime? Yes: getXrayVersion() and getSingBoxVersion() return core versions.
Which outbound does live stats track? By default it reads outbound>>>proxy uplink/downlink via Xray API (see _startStatusTimer() implementation).

⚙️ Utility Methods

await client.setSystemProxy('socks://127.0.0.1:10808');
await client.setSystemProxy(''); // disable proxy

final delay = await client.getServerDelay(
  url: 'vmess://...',
  type: DelayType.tcp,
);

print('Delay: ${delay}ms');

🖼 Screenshots

Android

Desktop

🔗 Related Links

👨‍💻 About the Author

I’m Amir Ziari, a full-stack developer passionate about privacy, VPN technologies, and Flutter performance.

I help developers build secure and reliable network apps.

🏁 Final Words

With flutter_v2ray_client_desktop, you can bring V2Ray/Xray & Sing-Box to desktop Flutter apps — with one unified API and cross-platform control.

Build your next-gen VPN or proxy tool with confidence ⚡

🚀 Introducing flutter_v2ray_client: Your Ultimate Flutter VPN Solution!

Amir Ziari — Wed, 24 Sep 2025 13:27:15 +0000

Hey Flutter fam! 👋 I'm absolutely thrilled to share my very first open-source package with you all! After months of hard work, I'm excited to introduce flutter_v2ray_client - a powerful Flutter plugin that brings the full power of V2Ray/Xray to your mobile applications! 🌟

🎯 What Makes This Special?

As someone who's passionate about privacy and performance, I wanted to create something that would make it incredibly easy for Flutter developers to integrate robust VPN and proxy functionality into their apps. This isn't just another wrapper - it's a thoughtfully designed, modern Flutter plugin with a clean API that you'll actually enjoy using! 💜

✨ Key Features That'll Blow Your Mind

🔐 Dual Mode Support

VPN Mode: Full system-level tunneling for complete privacy protection
Proxy Mode: Lightweight proxy-only connections for specific app traffic

🌐 Multi-Protocol Powerhouse

Seamlessly works with:

VMess - The classic choice for speed and reliability
VLess - Lightweight and efficient modern protocol
Trojan - Stealthy connections that blend with normal traffic
Socks - Universal proxy protocol support
ShadowSocks - Popular choice for censorship resistance

📊 Real-Time Monitoring Dashboard

Get live updates on:

Connection status and health
Upload/download speeds
Total traffic usage
Connection duration
Server response times

🎛️ Flexible Configuration

// Parse any V2Ray sharing link effortlessly
V2RayURL parser = V2ray.parseFromURL("your_v2ray_link_here");

// Customize everything to your needs
parser.inbound['port'] = 10890;
parser.log['loglevel'] = 'info';
parser.dns = {"servers": ["1.1.1.1"]};

🛡️ Smart Traffic Management

App Exclusion: Choose specific apps to bypass VPN traffic
LAN Bypass: Keep local network traffic flowing normally
Socket Protection: Prevents connection loops and ensures stability

🚀 Getting Started (It's Super Easy!)

1️⃣ Add to Your Project

flutter pub add flutter_v2ray_client

2️⃣ Basic Implementation

import 'package:flutter_v2ray_client/flutter_v2ray.dart';

final V2ray v2ray = V2ray(
    onStatusChanged: (status) {
        print('Connection status: ${status.state}');
    },
);

// Initialize and connect
await v2ray.initialize(
    notificationIconResourceType: "mipmap",
    notificationIconResourceName: "ic_launcher",
);

V2RayURL parser = V2ray.parseFromURL("your_v2ray_link_here");

if (await v2ray.requestPermission()) {
    await v2ray.startV2Ray(
        remark: parser.remark,
        config: parser.getFullConfiguration(),
        proxyOnly: false,
    );
}

🎨 Real-World Usage

Imagine building apps like:

Privacy-First Browsers 🛡️
Secure Messaging Apps 💬
Streaming Media Players 🎥
Corporate VPN Solutions 🏢
Developer Tools ⚙️

🌟 What's Under the Hood?

Android-First: Built with Xray 25.9.11 core for maximum performance
Modern Flutter: Compatible with Flutter 3.16.0+ and Dart 3.1.0+
Clean Architecture: Platform interface ready for iOS, Windows, Linux, macOS expansion
Google Play Ready: Full Android 16 KB page size support
Open Source: MIT licensed for maximum community benefit

🎯 Perfect For

✅ App Developers wanting to add VPN functionality
✅ Privacy Advocates building secure applications
✅ Network Engineers creating custom proxy solutions
✅ Students learning Flutter plugin development
✅ Companies needing enterprise VPN solutions

🛣️ Roadmap & Future Plans

I'm committed to making this the best Flutter VPN solution out there! Here's what's coming:

🚀 Performance Boost

Integration with hev-socks5-tunnel for blazing-fast speeds
Enhanced connection stability and resource efficiency

🌍 Multi-Platform Expansion

iOS Support (community donations welcome!)
Windows, Linux, macOS desktop versions
Cross-platform consistency

⚡ Advanced Features

Traffic routing and filtering
Custom UI components
Extended protocol support

💝 Community Love

This project thrives on community contributions! Whether you're:

🐛 Reporting bugs or suggesting improvements
💻 Contributing code to new features
📚 Improving documentation
🎨 Creating example apps
🌟 Spreading the word

Every contribution makes a difference! Check out our Contributing Guide to get started.

👨‍💻 About Me

Hey there! I'm Amir, a passionate Full Stack developer who loves creating tools that make privacy and security accessible to everyone. This is my first major open-source contribution, and I'm incredibly excited to share it with the community!

📱 Portfolio: Check out more of my work at Amir Ziari Portfolio

🎉 Final Thoughts

Building flutter_v2ray_client has been an incredible journey of learning and growth. I'm so grateful to the Flutter community for the amazing ecosystem that made this possible, and I can't wait to see what you'll build with it!

Ready to supercharge your Flutter apps with VPN capabilities? Give flutter_v2ray_client a try today! 🚀

Tags: #Flutter #VPN #V2Ray #XRay #Android #Proxy #Dart #OpenSource #Privacy #MobileDevelopment

Links:

Have questions? Found a bug? Want to contribute? I'd love to hear from you! Drop a comment below or reach out on GitHub. Let's build something amazing together! 🎯