# HxWarp for Windows

Personal WARP client — **local SOCKS**, **system proxy**, and **real TUN** via usque `nativetun` (Wintun). Same ice-cyan UI language as the macOS app.

> Not affiliated with Cloudflare. WARP / 1.1.1.1 are Cloudflare trademarks.
> Engine: [usque](https://github.com/Diniboy1123/usque) (MIT). TUN uses [Wintun](https://www.wintun.net/).

## Three modes (honest labels)

| Mode | What it does | Covers Go / OAuth without `ALL_PROXY`? |
|------|----------------|----------------------------------------|
| **仅 SOCKS** | `usque socks` on `127.0.0.1:19999` | **No** — set `ALL_PROXY` yourself |
| **系统代理** | HTTP CONNECT `:19998` + WinINET / IE proxy | **No** — browsers yes; Go/ACP often ignore WinINET |
| **真全局 (TUN)** | `usque nativetun` (Wintun, admin) | ✅ **Yes** — routes the whole system through the Wintun adapter |

Upstream usque implements `nativetun` on Windows (no extra root daemon needed),
but it only creates the Wintun adapter — it does not install routes. This
client fills that gap: it pins the MASQUE endpoint to the physical gateway and
moves the IPv4 default route onto the Wintun adapter (see
`internal/tunroute`), then reads the adapter's byte counters for the UI
waveform. When the QUIC/MASQUE data path is blocked (e.g. a host that is
already tunneling), the probe fails and the app falls back to the HTTP/2
transport, which carries the TUN traffic; if neither works it reports the
failure honestly instead of faking "connected".

## Requirements

- Windows 10/11 (amd64; arm64 usque zip also works if you fetch that arch)
- `usque.exe` next to `HxWarp.exe`, or in `windows/vendor/` (fetched by the `fetch-usque.*` scripts)
- **TUN:** administrator + `wintun.dll` beside `usque.exe` (also fetched by `fetch-usque.*` from wintun.net)

## Build (from macOS / Linux)

```bash
cd windows
./Scripts/fetch-usque.sh     # vendor/usque.exe
./Scripts/build.sh           # dist/HxWarp.exe
```

On Windows (one command — fetches usque + builds + assembles):

```powershell
cd windows
.\Scripts\build.ps1        # → dist\HxWarp.exe + usque.exe (+ wintun.dll if present)
.\Scripts\build.ps1 -Zip   # also create HxWarp-windows.zip
```

The `dist\` folder is ready to run:

```
HxWarp.exe
usque.exe
wintun.dll    # only needed for 真全局
```

## Run

```text
HxWarp.exe
```

Launches the **dedicated native desktop window** (via Windows WebView2) backed by the local engine (`127.0.0.1:19888`). Flags:

```text
HxWarp.exe -ui 19888      # custom UI port
HxWarp.exe -no-open       # don't open window (start silently in tray)
HxWarp.exe -connect       # connect immediately on launch
HxWarp.exe -elevated      # internal (used by the in-app relaunch)
```

The packaged build is a **native GUI desktop app** (no console window): it runs in
an independent window and minimizes to the **system tray** on close (`X` button). Tray interactions:

- Left-click → show / focus the desktop window
- Double-click → connect / disconnect
- Right-click → menu: 显示 / 连接·断开 / 退出

Single instance: launching HxWarp again focuses the existing desktop window. Logs go to
`%AppData%\HxWarp\hxwarp.log`. For a console build during development use
`go build` directly (omit `-H windowsgui`).

**开机自启 / 静默启动**: in 高级 you can toggle **开机自启** (registers
`HKCU\...\Run` so HxWarp starts at logon, silently in the tray) and **静默启动**
(never auto-open the window on launch). The Run entry launches with `-no-open`;
logon startup therefore always lands in the tray, ready to connect if 自动连接 is on.

## UI parity with macOS

The web UI mirrors the macOS client: a pulsing energy-ring hero, live
**throughput waveform** with ↓/↑ speed + session counters (counted by the local
HTTP gateway — system-proxy mode), **exit-gateway latency badges** with
“选最快 / 一键测速”, light/dark/system theme, and full zh/en i18n.

**真全局 (TUN)** needs an **administrator** process and `wintun.dll` beside
`usque.exe`. The app shows a “以管理员身份重启” button when it detects it is
not elevated; if `wintun.dll` is missing it fails with a clear message instead
of a cryptic usque error.

> Status: TUN mode brings up the Wintun adapter, installs the routing
> (endpoint pin + IPv4 default route via the TUN), waits for the interface to
> settle, then probes the real exit. QUIC is tried first and, if it cannot
> carry data, the app retries over HTTP/2 — in a double-tunnel environment
> (host also running WARP/代理) the HTTP/2 path is what actually works. The
> `TTL/Hop Limit too small` lines in usque's log are normal discovery packets
> (per upstream), not the failure.

Config: `%AppData%\HxWarp\prefs.json`  
usque account: `%AppData%\HxWarp\config.json` (reuses `~\.config\usque\config.json` if present)

## CLI without UI

```powershell
$env:ALL_PROXY='socks5h://127.0.0.1:19999'
curl https://cloudflare.com/cdn-cgi/trace
```

## Honesty

- System proxy only covers apps that honor WinINET. That is not a VPN.
- Official Cloudflare WARP Connected will fight nativetun for the default route — disconnect it first.
- First connect registers a WARP+ trial account via `usque register -a`.
