Amir Ziari

Posted on May 30 • Originally published at dev.to

flutter_singbox_client: A Modern Flutter VPN & Proxy Plugin Built on Sing-box

#flutter #vpn #proxy #singbox

A stateless, event-driven Dart wrapper for the Sing-box proxy core — TUN VPN mode, kill switch, Clash API, per-app proxy, and native support for WireGuard, Hysteria2, TUIC, VMess, VLESS, Trojan, Shadowsocks, and more, all in one Flutter plugin.

👋 Hey Flutter Fam!

If you've been following my journey, you know I shipped flutter_v2ray_client not too long ago — and the community response was absolutely incredible. Thank you! 🙏

But you kept asking me one thing:

"Amir, when are you bringing **sing-box* to Flutter?"*

Well — today is that day. 🎉

I'm beyond excited to introduce flutter_singbox_client — a powerful, modern Flutter VPN plugin and Flutter proxy library that wraps the Sing-box universal proxy core with a clean, stateless, event-driven Dart API.

Whether you're building a censorship-bypass VPN app, a privacy tool, or a custom proxy client in Flutter, this plugin gives you a production-ready foundation. 🌟

🤔 Why Sing-box for a Flutter VPN App?

V2Ray and Xray got us far — but the proxy world has evolved dramatically. Sing-box is the new gold standard for proxy cores:

Broader protocol coverage (WireGuard, Hysteria2, TUIC, etc.)
Better performance and modern TLS features (uTLS, Reality, ECH)
Actively maintained open-source community
Future-proof for years to come

If you're choosing a Flutter VPN library or a Flutter proxy library in 2026, Sing-box is the most future-proof core to build on. 💜

✨ Key Features

🔒 VPN Mode — Full device-wide TUN tunnel via Android VpnService

🌐 Proxy Mode — HTTP/SOCKS proxy without a TUN device — no VPN permission required

⚔️ Clash API — Runtime mode switching and outbound group control with latency testing

📱 Per-App Proxy — Include or exclude specific apps from the tunnel (split tunneling)

🌍 System Proxy — Register HTTP inbound as device-wide proxy on Android Q+

🔑 Kill Switch — Block all traffic at the OS level when the tunnel is down

📊 Live Traffic — Real-time upload/download speeds and session totals at ~1 Hz

🔌 Connection Tracking — Full per-connection metadata, lifecycle, and close control

📋 Live Logs — Real-time Go core log streaming with per-level filtering

⚠️ Fault Alerts — Dedicated fault stream for actionable service errors

🧠 Memory Limits — Go runtime soft memory cap (GOMEMLIMIT) with optional connection kill

🧪 Network Testing — Built-in STUN (NAT type, latency) and network quality (speed, RPM) tests

✅ Config Validation — Go core validation and JSON formatting before connecting

🔄 Hot Reload — Reload config without restarting the service or dropping connections

🚀 Boot Auto-start — Boot broadcast relay so your app can reconnect after device restart

📦 Zero Persistence — No database, no shared preferences, no file I/O for user data

🌐 Supported Protocols

Sing-box's protocol arsenal is unmatched. With flutter_singbox_client you get native support for:

VMess · VLESS · Trojan · Shadowsocks · Hysteria2 · TUIC · WireGuard · ShadowTLS · AnyTLS · Naive · Tor · SSH

Plus full support for V2Ray transports (WebSocket, gRPC, HTTPUpgrade, QUIC), TLS security (uTLS, Reality, ECH, ACME), FakeIP DNS, rule-based routing, and anti-censorship obfuscation.

🚀 Quick Start

1️⃣ Add to Your Project

dependencies:
  flutter_singbox_client: ^1.0.0

2️⃣ Configure Android

In android/app/build.gradle:

android {
    compileSdk 35
    defaultConfig { minSdk 23 }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = "17" }
}

3️⃣ Initialize

import 'package:flutter_singbox_client/flutter_singbox_client.dart';

final client = SingboxClient();
await client.initialize();

4️⃣ Connect

await client.connect(SessionOptions(
  config: myConfigJson,
  networkMode: NetworkMode.vpn,
  killSwitch: true,
  notification: NotificationConfig(
    title: 'VPN Active',
    showTrafficStats: true,
    showStopButton: true,
  ),
));

5️⃣ Listen to Events

// Live traffic stats
client.trafficStatsStream.listen((stats) {
  print('↑ ${stats.uplinkBps} bps');
  print('↓ ${stats.downlinkBps} bps');
});

// Connection state
client.serviceStateStream.listen((state) {
  print('State: $state');
});

// Faults & errors
client.faultStream.listen((error) {
  print('Error: $error');
});

📸 UI Showcase

Here's a peek at the production-ready example app:

🎨 Real-World Use Cases

Imagine building:

Privacy-First Browsers 🛡️ — Full TUN tunnel, zero traffic leaks

Secure Messaging Apps 💬 — Proxy layer over end-to-end encryption

Streaming Media Players 🎥 — Bypass geo-restrictions with Hysteria2

Corporate VPN Solutions 🏢 — Split tunneling for enterprise workflows

Censorship-Bypass Tools 🌍 — Reality + TUIC for the toughest networks

Developer Proxy Utilities ⚙️ — Route debug traffic, inspect connections live

🆚 flutter_singbox_client vs flutter_v2ray_client

Core Engine: flutter_v2ray_client uses Xray, flutter_singbox_client uses Sing-box

Protocols:

Hysteria2: ✅ Both (v3.2+ in v2ray) vs ✅ Native in singbox
TUIC: ❌ Not in v2ray vs ✅ In singbox
WireGuard: ❌ Not in v2ray vs ✅ In singbox
ShadowTLS / AnyTLS: ❌ Not in v2ray vs ✅ In singbox
Tor / SSH: ❌ Not in v2ray vs ✅ In singbox

Advanced Features:

Kill Switch: ❌ Not in v2ray vs ✅ In singbox
Hot Config Reload: ❌ Not in v2ray vs ✅ In singbox
Clash API: ❌ Not in v2ray vs ✅ In singbox
Connection Tracking: ❌ Not in v2ray vs ✅ In singbox
STUN / Network Test: ❌ Not in v2ray vs ✅ In singbox
Boot Auto-start: ❌ Not in v2ray vs ✅ In singbox
System Proxy: ❌ Not in v2ray vs ✅ In singbox

Bottom Line: Both packages are great — but flutter_singbox_client is the evolution. If you're starting a new Flutter VPN project in 2026, this is the one to pick. 🚀

❓ FAQ

What is flutter_singbox_client?
It's an open-source Flutter plugin that wraps the Sing-box proxy core in a stateless, event-driven Dart API. It lets Flutter developers build VPN and proxy apps with full TUN tunneling, kill switch, per-app proxy, and live traffic monitoring.

Is it free and open source?
Yes! GPL-3.0 on GitHub and pub.dev.

Which protocols does it support?
VMess, VLESS, Trojan, Shadowsocks, Hysteria2, TUIC, WireGuard, ShadowTLS, AnyTLS, Naive, Tor, and SSH — plus V2Ray transports and modern TLS features.

Does it support iOS?
iOS and macOS are in active development. Windows and Linux are planned. Android is fully supported today.

Can I use it in production?
Absolutely! It's built on Sing-box 1.14, supports Android API 23+, and is designed for production use.

Do I need root access?
No. Everything runs in user space through Android's standard VpnService API.

🌟 Tech Stack

Core Engine: Sing-box 1.14.0-alpha.20 (Go)

Android: API 23+ (Marshmallow), 16 KB page size ✅

Flutter: >= 3.19.0

Dart: >= 3.3.0

Java Target: 17

License: GPL-3.0

🗺️ Supported Platforms

Android: ✅ Done

iOS: 🔧 In Development

macOS: 🔧 In Development

Windows: 🗓 Planned

Linux: 🗓 Planned

🔗 Resources

flutter_singbox_client

flutter_v2ray_client (previous)

📦 Pub.dev
🐙 GitHub

💬 Share Your Thoughts

I'd love to hear from you in the comments:

Have you used Sing-box before? Which protocol is your go-to?
Are you building a VPN or proxy app? What features matter most?
Migrating from flutter_v2ray_client? What convinced you?
Privacy advocate? What's your biggest challenge when building censorship-bypass tools?

DEV Community