Sing-Box Launcher

Desktop platform for network routing and traffic analysis. 15+ VPN protocols, configuration depth and API at enterprise level. Built on top of the sing-box-lx fork (upstream sing-box + XHTTP transport + AmneziaWG 2.0) as execution engine — on every platform, including the Windows 7 32-bit legacy build.

Repository: https://github.com/Leadaxe/singbox-launcher

🌐 Languages: English | Русский

What it is

A cross-platform desktop client (Windows, macOS, Linux) that wraps sing-box and adds the entire surface around it: visual configurator, multi-subscription management, per-server switching with ping, network observability, declarative routing with preset bundles, a local HTTP API, and self-healing supervision.

Three layers that together define the product:

• User layer — one-button start/stop, subscription URL → working VPN flow, server picker with ping, declarative rules via checkboxes, Traffic Profiler window with per-process attribution.
• Power layer — Configurator with full sing-box rule semantics (CIDR, domain regex, process matching, sniff, GeoIP/Geosite via SRS), preset bundles with if/if_or conditions, DNS server selection with conditional rules.
• Headless layer — bearer-auth Debug API on 127.0.0.1, 24 endpoints covering state read/write, action triggers, traffic capture control, and a one-shot snapshot endpoint for support workflows.

Features

Connectivity

• 15 connection protocols — vless, vmess, trojan, shadowsocks, hysteria, hysteria2, tuic, ssh, wireguard, naive (https / quic).
• XHTTP transport — type=xhttp on vless/vmess/trojan nodes is parsed, generated into config.json, and round-tripped back to share URIs (no longer degraded to httpupgrade). Runs on the bundled sing-box-lx core.
• AmneziaWG 2.0 (AWG2) — obfuscation params on wireguard endpoints (jc / jmin / jmax, s1-s4, h1-h4, plus CPS packets i1-i5), parsed from both wireguard:// and awg:// URIs and emitted into endpoints[]. h1-h4 accept AWG 2.0 randomization ranges (lo-hi) — the core picks a fresh in-range value on every handshake (core ≥ 1.13.13-lx.6). AWG endpoint MTU is auto-clamped to 1280.
• Amnezia import — paste an Amnezia vpn://… link (the .vpn file content) or the raw [Interface]/[Peer] text of a WireGuard/AmneziaWG .conf straight into Sources: the launcher decodes the profile / detects the conf blocks and imports them as regular WG/AWG endpoints.
• Multiple sources per profile — subscription URLs and direct links (vless://, vmess://, …) can be mixed in a single configuration.
• Subscription provider compatibility — first-class support for HWID-binding panels (Marzban, Marzneshin, Remnawave, NashVPN, V2Board / Xboard) via the canonical XTLS subscription-header protocol (X-Hwid, X-Hwid-Limit, Announce, Subscription-Userinfo).
• Per-source raw cache — last working subscription body preserved on fetch failure (no broken config when provider is down).
• TUN inbound — system-wide VPN driver on Windows / macOS / Linux with auto-route, auto-redirect, and find_process enabled by default.

Routing & rules

• Preset bundles — community-maintained rule packs with typed variables, local SRS rule-sets, and conditional fragments (if / if_or). Toggle as checkboxes.
• User rules — five typed kinds: IP / CIDR, domain (suffix / keyword / regex), process (name or path regex), SRS URL, raw JSON.
• 17+ matchers — domain, IP CIDR, ports, network, protocol, process, package name, GeoSite / GeoIP via SRS, composite rules with invert.
• Per-rule outbound chains through selectors (urltest / failover).
• SRS auto-download — missing-file ⚠ badge on Configurator open; engine never tries to fetch SRS over a not-yet-up VPN.

DNS

• Multiple DNS servers with independent enable/disable (UDP / DoH / local).
• Per-domain DNS rules routing specific names to specific servers.
• Resolve strategy: prefer_ipv4 / prefer_ipv6 / ipv4_only / ipv6_only.

Network observability

• Traffic Profiler — always-on capture with 60-second × 3000-event rolling buffer, per-process attribution, CNAME-chain reconstruction, DNS-to-IP inferred matching.
• Issue classification — ⚠ DnsTimeout / ⚠ TcpRstEarly surfacing concrete diagnostic signals.
• Pre-session backfill — last 60 seconds of matching events copied into a fresh recording session.
• Three-stream Log Viewer — Internal launcher logs / Core sing-box log file / Clash API client log, with level filter and log-rotation safety.
• IP-check tools — STUN (UDP) and HTTPS providers (2ip.ru and others) for external IP verification.

Reliability

• Auto-restart with stability window — 3 attempts × 180 s, counter resets after stable operation; UI shows [restart 2/3] during recovery.
• Atomic file writes — stage → rename for config / state / settings; no half-written files on kill -9 or power loss.
• Power-event aware — sleep / resume listener; HTTP requests don't hang after wake.
• Configuration overlay — state stores template references plus user diffs; template bumps deliver new defaults automatically while personal edits stay on top.
• Auto-update subscriptions — hourly heartbeat refreshes only stale sources; immediate retry on VPN-event with anti-storm cooldown.

System integration

• System tray — start / stop, proxy switcher (when Clash API is on), open main window, exit. Active outbound mirrored in the tray.
• Keyboard shortcuts — ⌘R / Ctrl+R reconnect (kill sing-box for restart), ⌘U / Ctrl+U update subscriptions, ⌘P / Ctrl+P ping all proxies.
• CLI flags — -start (auto-start VPN on launch), -tray (start minimized to tray). Useful for autostart, system services, and headless deployment.
• Auto-loaders — proxy list restored on every sing-box start; active outbound persists across restarts.
• Share URI — right-click any proxy in the Servers tab → Copy link generates a share URI (vless://, vmess://, trojan://, ss://, hysteria2://, wireguard://) from the matching outbound in config.json.

Power tools

• Debug API — local HTTP API (24 endpoints, bearer-auth, off by default) for state read/write, action triggers, traffic capture control. See Headless control plane.
• Configurator — 6-tab visual editor (Sources / Outbounds / Rules / DNS / Settings / Preview) with schema validation, named state snapshots, atomic save.
• Snapshot for support — GET /debug/snapshot or Copy snapshot button packages template + state + cache + config into a single JSON for bug reports.
• Verbose toggle — 🔬 dbg button in Traffic Profiler flips sing-box log_level=debug with atomic rebuild and revert.

Distribution

• Cross-platform — Windows 10/11 (fully tested), Windows 7 via legacy build, macOS 11+ universal (Apple Silicon + Intel), Linux (build from source).
• 11 UI locales — English, Russian, German, Spanish, French, Italian, Japanese, Korean, Brazilian Portuguese, Turkish, Chinese.
• Self-update — pinned sing-box version auto-downloaded on mismatch; launcher self-update check at startup with notification (no silent installation).

Quick start

1. Download from GitHub Releases and install (see Installation).
2. Open the app → Core tab → click Download to fetch the matching sing-box binary (and wintun.dll on Windows). The core is the sing-box-lx fork (XHTTP + AmneziaWG 2.0) from its GitHub Releases — on every platform, including the Windows 7 32-bit legacy-windows-7 build (with a GitHub-proxy mirror fallback if GitHub is blocked).
3. Click Configurator → paste your subscription URL on the Sources tab → step through Outbounds / Rules / DNS / Settings / Preview → Save.
4. Back in Core → Start. Switch servers on the Servers tab, monitor traffic via the Traffic Profiler button in Diagnostics.

Command-line flags

singbox-launcher -start         # auto-start VPN on launch
singbox-launcher -tray          # start minimized to system tray
singbox-launcher -start -tray   # combined — headless autostart scenario

Useful for OS-level autostart (LaunchAgents / Task Scheduler / systemd --user) and for running the launcher as a background service that drives sing-box without showing a window.

Feature tour

Multi-subscription management

Add multiple subscription sources, each with its own update schedule and per-source raw cache. The Servers tab exposes selector groups (proxy-out, vpn ①, ru VPN, etc.) defined in your ParserConfig and shows per-server latency with one-click switching. Active outbound is mirrored in the system tray for quick swaps without opening the main window.

Per-source SubscriptionMeta surfaces upstream state — profile title, support URL, traffic usage (UploadBytes / DownloadBytes / TotalBytes), expiration date, last-fetch status, and provider announcements (📢 on success-with-announce, ⚠ on error-with-announce — actionable URL in the UI).

Share URI — right-click any proxy row in the Servers tab → first menu line shows the Clash API outbound type (lowercase: vless, vmess, trojan, selector, direct, …), then Copy link generates a share URI from the matching outbound in config.json (or from a WireGuard endpoint[] entry if the tag isn't an outbound). Convenient for moving a server to another device or sharing it with a teammate.

Declarative routing with preset bundles

Two-level rule model:

• Preset bundles (community-maintained template) — self-contained rule packs with typed variables (enum, dns_server, outbound with whitelists), local SRS rule-sets, conditional fragments (if / if_or), and DNS-server definitions. Toggle as checkboxes. Includes ready-made bundles like ru-direct (Russian traffic → direct), ads-all (ad-block via SRS), Telegram routing, BitTorrent splitting, and more.
• User rules — your own rules with 5 typed kinds: IP/CIDR, domains (suffix/keyword/regex), processes (name or path regex), SRS URLs, raw JSON.

Matchers cover the full sing-box surface: domain (4 variants), IP CIDR, ports, network, protocol, process, package name, GeoSite / GeoIP via SRS, composite rules with invert, per-rule outbound chains through selectors (urltest / failover).

The Subscription identification section (right side) implements SPEC 061 — the canonical XTLS / Remnawave subscription-header protocol. Random per-installation HWID, opt-out toggle, optional hash-based device model. Regenerate at any time.

DNS configuration

Per-DNS-server enable/disable, multiple transports (UDP / DoH / local), strategy (prefer_ipv4 / prefer_ipv6 / ipv4_only / ipv6_only), per-domain DNS rules pointing to specific servers (e.g. domain=mysite.ru → test server), default DNS resolver selection. SRS-based domain rules supported via the same library as routing rules.

TUN, diagnostics, and power tools

TUN inbound (system VPN driver), MTU, stack selection (system / gvisor), TLS root certificate store, URLTest target and interval, custom proxy-in inbound — all in the wizard, no JSON editing required.

Power tools on the right:

• Log window — three parallel streams (Internal launcher logs / Core sing-box log file / Clash API client log), level filter, log rotation safe.
• Logs / Config folder — one-click open in Finder/Explorer.
• Kill Sing-Box — force restart; the supervisor handles the rest.
• Traffic Profiler — see below.
• IP check services — STUN (UDP), HTTPS IP-check providers (2ip.ru, etc.).
• Debug API — toggle the local HTTP API; bearer token generated on first enable and preserved across off/on cycles.

Traffic Profiler

Always-on background capture with a 60-second × 3000-event rolling buffer. Two data sources joined by connection ID: Clash API /connections (per-process metadata from sing-box) and sing-box log tail (DNS resolves, router matches, outbound dials).

Per-process view has four sub-tabs:

• Live — newest-first event stream with color coding by kind.
• Domains — aggregated unique domains sorted by bytes; tap to see CNAME chain, all IPs, outbound chain, issues.
• IPs — useful for hostless connections (raw TCP without SNI sniff).
• Connections — per-connection timeline; tap to see rule, outbound, CNAME chain, issues.

Issue classification surfaces concrete problems: DnsTimeout (DNS resolver did not respond), TcpRstEarly (TCP closed <1s with 0/0 bytes — firewall RST / TLS fail / block). Verbose mode (🔬 dbg) toggles log_level=debug with atomic config rebuild and revert. Pre-session backfill copies the last 60 seconds of matching events in