An all-in-one Windows proxy app with zero user-installed dependencies:
a Rust core supervises an Xray VLESS+REALITY tunnel to your own VM, bonds
multiple physical uplinks, imports vless:// share links, and manages the
Windows system proxy — all behind a Material You (Material Design 3)
GUI with dynamic color.
Since v0.3 MultiTunnel combines the functions of a v2rayN-style client and net-merge-style link bonding out of the box: the SOCKS5/HTTP inbounds, the routing table, the link bonding engine and the profile store all run in-process, and the Xray engine binary is fetched automatically on first connect. Nothing to install beside the app itself.
| Binary | What it is |
|---|---|
multitunnel.exe |
the all-in-one: gui (Material You app), profiles, import, connect, doctor, generate, version |
multitunnel-tray.exe |
the legacy v0.2 notification-area (tray) app (Windows subsystem, no console) |
You run everything on hardware you control: the proxy core (Xray) on your own cloud VM, everything else on your own PC. MultiTunnel sets and clears the Windows system proxy, keeps the tunnel alive (fail-open), and never lets the engine outlive the app (Windows kill-on-close job objects).
If you just want it working, read QUICKSTART.md first — the whole path is about ten minutes.
your Windows PC your VM (cloud, static IP)
┌──────────────────────────────────────────┐ ┌────────────────────────────────────┐
│ Material You GUI (iced + mt-m3) │ │ │
│ │ Arc<dyn MtService> │ │ │
│ ▼ │ │ │
│ RealService (root crate) │ │ │
│ ├─ ProfileStore (mt-links) │ │ │
│ │ vless:// import, subscriptions │ │ │
│ ├─ ProxyServer (mt-net) │ VLESS + │ xray (systemd, User=nobody) │
│ │ SOCKS :10808 / HTTP :10809 │ REALITY │ - listens on 0.0.0.0:8443 │
│ │ Router: private CIDRs → direct │ ═════════════▶ │ - REALITY borrows the TLS cert │
│ │ merge: round-robin (default) │ TCP :8443 │ of the gateway already on │
│ ├─ ManagedEngine (mt-engine) │ │ 127.0.0.1:443 (serverNames) │
│ │ one Xray child per link, │ │ │ as its camouflage │
│ │ kill-on-close job, respawn │ │ ▼ freedom outbound │
│ ├─ EngineLocator (mt-platform) │ │ default routing -> the internet │
│ │ engine self-download + SHA256 │ │ │
│ └─ sysproxy (WinINET, HKCU) │ │ │
│ fail-open, snapshot + self-heal │ │ │
└──────────────────────────────────────────┘ └────────────────────────────────────┘
Workspace layout (Mixture-of-Experts build: one expert crate each, frozen
contracts in harness/CONTRACTS-S6.md):
| Crate | Role |
|---|---|
mt-links |
share-link parsing (vless:// strict REALITY-only), profile store, subscriptions, v0.2 migration |
mt-net |
the data plane: SOCKS5 + HTTP inbounds, routing table, link bonding (round-robin default / failover / lowest-latency), quarantine |
mt-engine |
supervised Xray child processes: respawn with backoff, kill-on-drop + kill-on-close job objects |
mt-m3 |
Material You design tokens with real HCT dynamic color (material-colors) |
mt-platform |
engine locator/self-download (SHA256SUMS-verified), autostart, platform dirs |
mt-service |
the frozen UI service contract (state machine, events) |
mt-app |
the iced 0.13 Material You GUI (tiny-skia renderer) |
| root | RealService wiring, the v0.2 CLI (connect/doctor/generate/tray) |
Walking through one request: the application speaks to the loopback proxy
because MultiTunnel has set the WinINET system proxy to 127.0.0.1:10809.
The router sends private/LAN CIDRs direct and everything else through the
VLESS+REALITY outbound; because mux is off, every proxied connection is its
own TCP stream, so a multi-link setup can spread connections across
uplinks (connection-level bonding, round-robin by default — failover and
lowest-latency selectable). On the VM,
xray terminates REALITY on port 8443 — an unauthenticated handshake is
proxied to the real gateway, which is what makes the port look like an
ordinary HTTPS endpoint — and exits through a plain freedom outbound.
These are deliberate design contracts, not accidents; changing any of them breaks something subtle.
- Mux must stay OFF. Bonding works by spreading individual TCP
connections across uplinks. A muxed tunnel collapses all traffic into a
single stream, and one stream always rides one link — bonding would be
defeated. The generated client config pins
"mux": { "enabled": false }. - Loopback-only inbounds. The proxy plane exposes only SOCKS/HTTP on
127.0.0.1and never creates a TUN inbound. - LAN traffic stays local. The stock routing rules send every private
CIDR (
10/8,172.16/12,192.168/16, loopback, link-local, ULA) to adirectoutbound, and the system proxy override lists the same ranges — local network traffic never takes the tunnel. - Fail-open proxy policy. The system proxy is a machine-wide setting; a
dead proxy pointing at a dead tunnel means "no internet". If the engine
dies, MultiTunnel restarts it with backoff; if the restart budget is
exhausted, it restores (clears) the system proxy so normal browsing keeps
working, and marks the state
Failed. True fail-close is out of scope. - The engine can never be orphaned. On Windows every Xray child runs inside a kill-on-close job object: even if MultiTunnel itself is killed (Task Manager, Ctrl+C, power loss), the kernel tears the engine down with it.
- Stale-proxy self-heal. A run that dies without disconnecting can leave the registry pointing at a dead listener; the next connect (CLI or GUI) restores a clean proxy state at step 0 before bringing the tunnel up again.
- Strict share-link parsing (D10).
vless://imports accept onlysecurity=reality,type=tcp, flowxtls-rprx-visionor unset, a canonical UUID, and well-formedpbk/sid; unknown parameters are ignored, and no error message ever echoes credential values.
The supervised connect sequence, in order: self-heal any stale system
proxy → write the generated Xray config → start the engine and wait for
the SOCKS port → probe the full chain through the tunnel (fail fast: stop
engine, restore proxy, state Failed) → set the system proxy (non-fatal).
While connected, the event pump doubles as a supervisor: link health is
checked on a 5 s cadence, and all-links-down for three consecutive checks
fires the fail-open give-up (proxy restored, state Failed). Engine
restarts back off 1 s, 2 s, 4 s, ... capped at 30 s.
server/setup-xray-reality.sh installs the VLESS+REALITY endpoint on your own
Ubuntu/Debian VM in one run:
sudo DOMAIN=your-gateway.example.org bash server/setup-xray-reality.shIt resolves the latest Xray-core release via the GitHub API (never a
hardcoded version), downloads and verifies the archive, installs
xray to /usr/local/bin/xray with geo assets to /usr/local/share/xray/,
generates a fresh UUID / X25519 key pair / shortId, writes
/usr/local/etc/xray/config.json (validated with xray run -test), installs a
hardened systemd unit (User=nobody, ProtectSystem=strict,
NoNewPrivileges, auto-restart), and starts it. At the end it prints the
firewall checklist for the VM and either a ready-to-paste "server" block
(legacy config.json path) or a full vless:// share link (v0.3 GUI/profiles
path).
Environment knobs: DOMAIN (required — the existing gateway domain whose TLS
certificate the REALITY handshake borrows), PORT (default 8443), DEST
(default 127.0.0.1:443 — the gateway on the same VM), INSTALL_ROOT
(default /usr/local), FORCE=1 (overwrite an existing config — regenerates
all credentials). The REALITY private key is written only to the server
config; the script never prints it and it never leaves the VM.
Per-connection spreading (since v0.3) assigns each TCP connection to ONE link. Stream bonding splits the BYTES of every connection across ALL bonded adapters and merges them on the server — the net-merge promise at stream granularity:
- The client runs one carrier per bonded adapter: an ordinary
VLESS+REALITY connection (per-adapter engine,
sendThroughpinned) whose target is the merge daemon on the server (127.0.0.1:<merge port>, reached through the tunnel). No new ports are exposed. mt-bondframes the streams (24-byte headers: HELLO/OPEN/DATA/CLOSE/ ACK/PING/PONG), stripes DATA frames round-robin across carriers, reorders per session, and replays unacked frames on a carrier that dies — a Wi-Fi drop mid-download costs zero bytes. Cumulative ACKs bound the replay window; TCP-native backpressure provides flow control.mt-merge-server(the daemon, installed byserver/setup-merge-daemon.sh) accepts the carriers, re-merges each session in order, dials the real target, and splits the reverse traffic back across all carriers.- Bonding mode is a setting:
per-connection(default, no server changes) orstream. Stream mode falls back to per-connection with a log line when the daemon is unreachable — never a black hole.
The Status tab verifies the whole path live: one row per carrier (RTT, wire bytes), a Task-Manager-style bandwidth graph scaled to the window with a color-coded legend (down = primary, up = tertiary), per-adapter traffic graphs behind the arrow on every Adapters-tab row, and the Exit identity card (see below).
Exit identity (v0.5) — no hidden hops, verifiable in one click
The Status tab's "Check exit IP" rides the live tunnel and reports the exit IP with geo/ISP plus a verdict against the active profile's server:
- exit == server -> single hop. MultiTunnel never inserts intermediary servers: each adapter's engine dials the profile endpoint directly.
- exit != server -> the exit is the SERVER's own egress (e.g. a VPN on
the VM — the documented ProtonVPN scenario in
server/setup-xray-reality.sh). If you expected the GCP IP and see a VPN provider's ASN instead, that is the VM's default route, not an added hop.
- Double-click
multitunnel.exe— since v0.3.1 the bare launch IS the GUI (the orphan console a double-click allocates is freed automatically;multitunnel guifrom a terminal does the same and keeps the console). The Material You window opens (theme seed is configurable; dark mode included). - Paste a
vless://share link on the Servers screen — a preview shows protocol/endpoint before you add it. Or use the CLI:multitunnel profiles add "vless://…"thenmultitunnel profiles use <tag>. - Flip the connect switch. On first connect the engine is downloaded and
verified automatically (see the mt-platform locator;
MULTITUNNEL_ENGINE_URLcan point at a mirror). The Routing screen edits the rule table (private CIDRs go direct by default); Settings covers the system-proxy flag, merge policy, autostart and theme.
Closing the window (or Ctrl+C in the console) disconnects cleanly — the
system proxy is always restored. multitunnel gui --smoke runs the app
headless for CI.
Settings and profiles live in the platform config dir
(%APPDATA%\MultiTunnel unless overridden): profiles.json (the multi-
server store) and settings.json (ports, rules, theme, flags). Neither
file contains secrets beyond the profile credentials themselves; profile
files are written with restrictive permissions.
MultiTunnel reads config.json next to the executable (or the path given with
-config <path>) for the connect/doctor/generate commands and the tray
app. Start from config.example.json; the schema is camelCase and every
field has a default. config.json is gitignored — credentials never
belong in the repo. multitunnel import "vless://…" fills its server block
from a share link (only the six server.* fields are patched — your local
ports and paths survive).
| Field | Default | Meaning |
|---|---|---|
server.address |
35.208.99.240 (template prefill) |
the VM's public address — required, no fallback when cleared |
server.port |
8443 |
VLESS+REALITY port on the VM |
server.uuid |
— (required) | client UUID, from the server script's output |
server.sni |
— (required) | the gateway domain (REALITY serverName) |
server.publicKey |
— (required) | X25519 public key (client half) |
server.shortId |
— (optional) | REALITY shortId; may stay empty |
local.listen |
127.0.0.1 |
loopback bind address for the core's inbounds |
local.socksPort |
10808 |
loopback SOCKS inbound |
local.httpPort |
10809 |
loopback HTTP inbound (the system proxy target) |
paths.xray |
bin/xray.exe |
Xray core binary (relative paths resolve against the exe dir) |
paths.netMerge |
net-merge |
net-merge executable (legacy bonding) |
paths.xrayConfig |
xray-client.json |
where the generated Xray config is written |
paths.logDir |
logs |
core log (xray.log) lives here |
paths.stateDir |
state |
proxy snapshot, raw status dumps |
netMerge.enable |
true |
turn legacy net-merge bonding on/off with the tunnel |
behavior.systemProxy |
true |
set/clear the WinINET system proxy with the tunnel |
behavior.proxyOverride |
localhost;127.*;10.*;192.168.*;172.16.* … 172.31.*;<local> |
proxy bypass list |
behavior.probeTarget |
example.com:80 |
periodic full-chain probe target (host:port) |
behavior.probeIntervalSec |
60 |
probe interval in seconds |
behavior.restartMax |
5 |
core restart budget after failures (0 = never restart: give up at once and restore the proxy) |
Conventions: fields left empty fall back to these defaults on load — except
server.address (required; an empty value is rejected by validation) and
behavior.restartMax (0 means never restart, not the default); purely
relative paths are resolved against the executable's
directory (absolute or drive-rooted paths are used as-is). Validation requires
server.uuid, server.sni and server.publicKey (the error names exactly
the missing fields and points at the server script), and the SOCKS/HTTP ports
must differ.
Both binaries accept -config <path> / --config <path> to override the
config location (legacy commands only; the GUI path uses settings.json).
Usage: multitunnel [command] [-config <path>]
(none) launch the all-in-one Material You GUI (default — v0.3.1)
gui launch the all-in-one Material You GUI (--smoke: headless CI run)
profiles manage the multi-server profile store (list/add/use/remove/export)
import fill config.json's server block from a vless:// link
connect connect headless (legacy v0.2 path), run until Ctrl+C
generate write the generated Xray client config and exit
doctor check environment (binaries, config, ports)
tray pointer only: the tray app is the separate multitunnel-tray.exe
version print version
- Double-click /
multitunnel gui— the all-in-one app (see above). Closing the window or Ctrl+C disconnects and restores the system proxy. A GUI launch from Explorer detaches its throwaway console, and a start failure without a usable console is reported in a MessageBox — the app can no longer die invisibly. multitunnel profiles list— protocol/address/port/tag per profile, active marked; never prints credentials.profiles add <share-link>(previews, then upserts),profiles use <tag-or-id>,profiles remove <tag-or-id>,profiles export [tag](prints a share link — that is its purpose; vmess profiles cannot be re-exported).multitunnel import "vless://…"— patches only the sixserver.*fields ofconfig.json; everything else (ports, paths, behavior) survives. Writes the file atomically with restrictive permissions.multitunnel doctor— environment check; exits 1 if anything fails. Checks: elevation, the Xray binary, net-merge reachability (warns when bonding is disabled), free SOCKS/HTTP ports, writable log/state dirs, and a parseableprobeTarget. The config is loaded and validated first.multitunnel connect— legacy headless connect: elevates via UAC on Windows when needed, brings the tunnel up, and supervises untilCtrl+C.Ctrl+Cdetaches with the system proxy still set; the nextconnectself-heals it.multitunnel generate— renders the Xray client config topaths.xrayConfig(0600 on POSIX; default user-profile ACL on Windows — it embeds the VLESS credential) and exits.multitunnel-tray.exe— the legacy tray app. Elevates via UAC when needed, readsconfig.jsonbeside the executable, and puts an icon in the notification area with Connect/Disconnect, raw status, log folder, config editing and clean Exit.
Stable Rust (MSRV 1.97 — material-colors 0.5.0 requires it). From a checkout:
cargo build --release # multitunnel + multitunnel-tray
cargo build -p mt-app # the standalone GUI dev binary (mock backend)
cargo test --workspace # full suite (321 tests)-
Native Windows with the MSVC toolchain is the supported way to produce release binaries (this is what CI uses).
-
Cross-checking from Linux without a mingw toolchain works via cargo-zigbuild, which uses zig as the linker driver:
rustup target add x86_64-pc-windows-gnu cargo install cargo-zigbuild cargo zigbuild --target x86_64-pc-windows-gnu --release cargo zigbuild --target x86_64-pc-windows-gnu --release -p mt-app
-
The Windows-only dependencies (
windows-sys,winreg) are feature-gated behindcfg(windows); a Linux build compiles the library and console binary with stubs, which is how the test suite runs on Linux CI. -
mt-app.exeis a development binary (mock backend); the shipped all-in-one GUI ismultitunnel guiinsidemultitunnel.exe, which links the real service.
.github/workflows/ci.ymlruns on every push tomainand on pull requests:cargo test --workspaceon a matrix ofubuntu-latestandwindows-latest(plus the headless GUI smoke run on ubuntu); a lint job enforcingcargo fmt --all --check,cargo clippy --workspace --all-targets -- -D warningsand the same again for thex86_64-pc-windows-gnutarget (zig cc shims); and a cross-check job runningcargo zigbuild --workspace --target x86_64-pc-windows-gnu..github/workflows/release.ymlruns on tags matchingv*: on awindows-latestrunner it runs the full workspace gates (fmt --all,clippy --workspace,test --workspace) first (tag pushes bypass the CI workflow, so a release tag must never ship an untested build), then builds--release, packages both executables together withconfig.example.json,LICENSE,THIRD_PARTY_NOTICES.md,README.md,QUICKSTART.mdandserver/setup-xray-reality.shinto a zip, and publishes the GitHub Release (fail_on_unmatched_filesis set so a packaging typo fails loudly instead of shipping an empty release).
- Credentials.
config.json,profiles.jsonand the generatedxray-client.json/engine configs hold the VLESS UUID and REALITY public parameters; they are gitignored (onlyconfig.example.jsonis committed) and written with mode 0600 on POSIX / default user-profile ACL on Windows. On the server, the REALITY private key lives only in the VM's/usr/local/etc/xray/config.json(root-owned) and is never printed by the setup script. - No secrets in logs or errors. Parse errors name lengths and field positions, never credential values; download errors never echo URLs that may carry embedded tokens; logs contain engine output and state summaries only.
- Engine integrity. The self-downloaded engine is verified against the
published SHA256SUMS when present (advisory by default;
MULTITUNNEL_ENGINE_STRICT=1refuses on mismatch — see DECISIONS D14), installed atomically from a private staging dir with zip-slip protection. - Unsigned binaries. Release artifacts are not code-signed: expect the Windows SmartScreen / "unknown publisher" warning and the UAC prompt. Administrator rights are required for the HKCU proxy writes (the v0.3 GUI path needs no net-merge/wintun driver). Only run binaries you built yourself or downloaded from this repository's Releases.
- Fail-open. See the design section: on unrecoverable failure the system proxy is restored rather than left pointing at a dead tunnel. After an abrupt termination the proxy can remain set until the next connect run cleans it up.
MultiTunnel is MIT-licensed — see LICENSE. Third-party components (compile-time crates including the fonts embedded in the GUI, and the runtime-fetched Xray-core engine, which is not redistributed) are listed in THIRD_PARTY_NOTICES.md.
The project is developed under a staged harness with parallel adversarial
review — see harness/HARNESS.md for the protocol,
harness/ROADMAP.md for the roadmap and stage history,
and harness/memory/ for decisions, consensus verdicts and agent reports.