singbox-launcher

Sing-Box Launcher

** Language**: English | Русский Desktop platform for network routing and traffic analysis. 13 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. Drives its own core and, over a mutually-authenticated channel, the cores of remote machines — a router or a VPS — each with its own config.

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

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.

Four 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.
• Fleet layer — the Remote tab manages other machines (router, VPS, another Mac) running the core as a daemon: each has its own wizard profile and built config, its own Start/Stop and Deploy, its own traffic profiler and host telemetry window.
• Headless layer — bearer-auth Debug API on 127.0.0.1, ~30 local endpoints covering state read/write, action triggers, traffic capture control, and a one-shot snapshot endpoint for support workflows.

Features

Connectivity

• 13 connection protocols — vless, vmess, trojan, shadowsocks, hysteria2, tuic, anytls, masque, ssh, socks / socks5, naive (https / quic), wireguard / AmneziaWG, plus Amnezia vpn:// profiles.
• 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.14.0-lx.1-rc.17). 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.
• Tailscale — the launcher can be a tailnet node itself: Add server → Tailscale builds a tailscale endpoint (auth key, control URL, hostname, ephemeral, accept routes, exit node) together with its MagicDNS server (*.ts.net) and a route for 100.64.0.0/10, so tailnet hosts resolve and are reachable right after Rebuild. Every node gets its own state directory under bin/tailscale/. Requires a core built with with_tailscale — 1.14.0-lx.31 or newer; on an older core such a node is dropped with a warning in the build report instead of failing the whole config. The auth key is one-off: it is consumed at first login, after which the node identity lives in the state directory. Pick a tailnet node in a Direction only if it has an exit_node — without one it opens the tailnet, not the internet.
• 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.

Core engines and remote machines

• Two core engines behind one seam. Classic (default, all platforms) spawns and supervises sing-box run and talks to it over the Clash API. Daemon (macOS) drives the core inside a long-lived system service (sing-box lxd) over gRPC + admin REST — the same in-process model the Android line uses. UI, tray, shortcuts and the Debug API all go through the active engine, so nothing above the seam knows which one is running.
• Daemon mode benefits — sudo once (the launcher prepares the install command for your own Terminal and never runs anything privileged itself), the VPN keeps running after you quit the launcher (opt-out toggle), config changes swap the core in place with subprocess validation and auto-rollback to the last working config, plus richer observability: live status, connections, core logs and a balancer pool view over gRPC.
• Remote machines — pair a router / VPS / another Mac over mTLS with a one-time invite (address#fingerprint#code). Each machine gets its own registry entry (name, platform, architecture, address), its own wizard profile and built config.json, and its own Start / Stop / Deploy — a config built for the router can no longer be deployed to the VPS.
• Deploy delivers resources, not just JSON — rule-sets and subscription bodies the machine's config references are shipped into its resource store alongside the config.
• Host telemetry window — per-machine CPU / memory / storage / network tables answering "why is the router slow" independently of the core's own traffic view.

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).
• Hop chains — a route through several hops in a row (you → hop 1 → hop 2 → the site), added from the ⋮ menu on Sources as a third source kind next to a subscription and a single server. A position may be a node, a subscription group or a Direction, so switching a group changes the path without a restart. The chain then behaves like any other server: Directions pick it up and an auto-select group measures the whole multi-hop route. The Info window probes it layer by layer, so the (+N) delta names the hop that costs the latency. Needs a core built with with_lx_chain; on an older one the chain simply does not appear and the launcher says which core you have.
• Directions — a named routing target with its own node filter and an optional auto-select twin. A rule points at the Direction, not at a node tag: provider tags are regenerated on every subscription update, so a node-targeted rule breaks the moment the provider renames it.
• Fold a subscription into a group — one checkbox instead of the old four flags: a fifty-node subscription arrives as one entry (selector, auto-select, or a selector with an auto-select default).
• SRS auto-download — missing-file ⚠ badge on Wizard open; engine never tries to fetch SRS over a not-yet-up VPN.

DNS

• DNS servers set up with a form, not raw JSON — one form per kind that people actually use (UDP, TCP, DoT, DoH and a group), with the fields that kind needs and nothing else. The channel a query travels through is picked from the list of Directions. Raw JSON stays on its own tab for the types without a form (hosts, fakeip, dhcp, quic/h3).
• DNS groups — several resolvers behind one name: the group queries its members and takes the fastest answer, so one dead resolver no longer stalls name resolution.
• 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. A paired machine gets its own profiler instance and window (fed by its gRPC streams), so two machines can be watched side by side.
• 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 server list (Local or Remote) → 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 (~30 local endpoints plus the /remote/* and /daemon/* groups; bearer-auth, off by default) for state read/write, action triggers, traffic capture control. See Headless control plane.
• Configurator — 7-tab visual editor (Target / Sources / Directions / Rules / DNS / Settings / Files) with schema validation, named state snapshots, atomic save. The Target tab decides which machine the config is built for — this one, or a paired remote machine with its own OS/architecture and optional gateway role.
• LX Backup — carry settings between the desktop launcher and LxBox on your phone: Settings → Backup exports subscriptions, servers, rules, DNS and portable variables into one file and imports one back. Anything the other side has no place for travels along untouched, so a backup that passed through the phone does not come back impoverished.
• Snapshot for support — GET /debug/snapshot or Copy snapshot button packages template + state + cache + conf