Usque — Unofficial client compatible with Cloudflare® WARP® services

English · 简体中文 · 日本語 · 한국어 · Русский · فارسی

PR Check CI Build MIT License

# Usque Usque is an unofficial client compatible with Cloudflare® WARP® services for Windows, Linux and Android / Android TV. It combines a system VPN, SOCKS5, and HTTP proxy in a native Flutter interface, powered by a Rust MASQUE engine. > [!IMPORTANT] > Download official packages only from [GitHub Releases](https://github.com/GeorgeXie2333/usque-app/releases). Pull Request artifacts, local builds, and untagged binaries are not official. Development-branch documentation can describe changes not yet released; check the release notes and documentation at your package's tag. Usque is an independent project. It is not affiliated with, sponsored by, or endorsed by Cloudflare, Inc. Cloudflare and WARP are trademarks and/or registered trademarks of Cloudflare, Inc. in the United States and other jurisdictions. Use of consumer WARP services remains subject to Cloudflare's terms and privacy policy. ## Screenshots

Windows

Usque Home on Windows

Android

Usque Home on Android
English interface previews rendered from the current source, shown disconnected. ## Download and install This branch prepares **v0.3.3 / 0.3.3+29**, bringing Linux desktop support, optional Proton VPN and improvements to everyday connections. Check [GitHub Releases](https://github.com/GeorgeXie2333/usque-app/releases) and the documentation at the matching tag for published versions. The release targets twelve user installers, plus two Windows MSI files reserved for in-app updates: | Platform | Minimum OS | Packages | | --- | --- | --- | | Windows | Windows 10 2004, build 19041 | x64-v2 installer EXE or ARM64 installer EXE | | Linux (v0.3.3) | Ubuntu 22.04+, Debian 12+, supported Fedora; systemd | amd64 / arm64 × AppImage / deb / rpm | | Android / Android TV | Android 8.0, API 26 | arm64-v8a, x86_64, or armeabi-v7a APK | | Android / Android TV | Android 8.0, API 26 | Universal APK containing all three ABIs | Linux uses generic x86-64 or ARM64 and AppImage/deb/rpm packages. Verify its Ed25519 manifest before installation. The first AppImage VPN setup installs a background service with administrator authorization; credentials require an unlocked Secret Service keyring. See the [Linux desktop guide](docs/LINUX_DESKTOP.md) for GNOME/KDE, X11/Wayland, recovery and the tested coverage. Choose the package matching your device architecture. Windows x64 requires a CPU supporting **x86-64-v2**; ARM64 Windows uses the native ARM64 package. Use the larger universal APK when the Android ABI is unknown. Before installing, compare the package SHA-256 with `SHA256SUMS` and GitHub's asset digest, then verify the signer fingerprint published in the release notes. Stop if any value differs. Pre-1.0 Windows/Android packages use fixed, project-controlled self-signed certificates. Windows may show an unknown-publisher warning; Android packages are installed outside Google Play. Do not disable antivirus or the firewall, or import certificates from unofficial packages, to bypass a warning. See [Installation and removal](docs/INSTALLATION.md) for upgrades, uninstall, recovery, and Android developer-verification details, and [Code signing](docs/CODE_SIGNING.md) for official identities. Updates require confirmation before downloading and use the platform installer; there is no unattended installation. Upgrading from v0.3.1 migrates configuration from schema 24 to 26, which v0.3.1 and older clients cannot read. Review [configuration compatibility](docs/INSTALLATION.md#configuration-compatibility-when-upgrading) and any required pre-upgrade backup before upgrading; reinstalling an older package does not reverse the migration. ## First connection 1. Install a [verified official package](docs/INSTALLATION.md#verify-before-installing) and open Usque. 2. Complete the first-run permissions and terms steps. Android setup requests only optional notifications. VPN authorization is requested when connecting with VPN output and may disconnect another VPN; proxy-only connections do not request it. Register a Consumer WARP® account, optionally with a WARP License Key. If setup was interrupted, check the saved result before registering again. Usque does not accept new WARP Secret imports. 3. Open **Proxy**. Turn on **TUN** (Windows) or **VPN** (Android) under **Device traffic**, and the **SOCKS5 proxy** or **HTTP proxy** switch at the top of its own section, then connect from Home. These switches take effect immediately; listener address and port edits require **Apply changes**. | Connection option | When to use it | | --- | --- | | VPN/TUN | Route system traffic through the tunnel, with your bypass and Android per-app rules. | | SOCKS5 | Give compatible applications a local TCP/UDP proxy; remote DNS is the default. | | HTTP proxy | Give compatible applications a local HTTP proxy, including HTTPS through CONNECT. | | Windows system proxy | Point Windows proxy settings at Usque's HTTP proxy; HTTP output must be enabled. | VPN, SOCKS5 and HTTP are enabled by default; Windows system proxy is off. They share one WARP connection and can run together. Turning off every output keeps the WARP connection open, but no app traffic uses it. Each account stores its own credentials; only one account connects at a time. Network settings are shared by all accounts. ## Features - Optional [chain proxy](docs/CHAIN_PROXY.md): open **Proxy → Chain proxy** for **OpenVPN**, **WireGuard**, [**WARP via WireGuard**](docs/WARP_WIREGUARD.md), [**Proton VPN**](docs/PROTON_VPN.md), **VPN Gate**, **HTTP**, and **SOCKS5**, in that order. Native Proton setup is under validation; live sign-in, the human puzzle and the full tunnel remain untested. Import VPN configurations or add proxy servers, then select and apply one. VPN, SOCKS5 and HTTP share the exit; explicit direct rules still apply. Off by default. - Opt-in [experimental L4 mode](docs/L4_PROXY.md) proxies TCP over HTTP/3. Without an OpenVPN TCP chain, it does not forward ordinary UDP; applications that need UDP may not work. Auto does not select L4. - Automatic HTTP/3 connections with HTTP/2 fallback. IPv4 and IPv6 connection attempts help find a reachable endpoint; supported H3 network changes can migrate the connection. See [path behavior](docs/h3-path-infrastructure.md). - Full-tunnel VPN, tunneled DNS, Kill Switch, LAN access and [DIRECT/REJECT/PROXY routing rules with Ads](docs/ROUTING.md). Custom domains and CIDRs support more-specific exceptions; conflicts are checked before saving. Ads rules are prepared automatically when enabled and applied, checked every seven days while the app runs, and take effect on new requests without reconnecting. Rule details provides status, source and manual updates. - Custom [WARP exit DNS](docs/WARP_DNS.md): open **Settings → Advanced network settings → WARP DNS**, choose Plain DNS, DoH or DoT, and select **Apply changes**. Changing DNS reconnects an established session; the final chain exit keeps its own DNS policy. - Optional country-based direct routing. Download the selected countries' GeoIP data and the global GeoSite catalog separately. Usque uses domain rules when the name is visible, otherwise IP rules; unknown destinations stay in the tunnel. - Local [network diagnostics](docs/network-doctor.md) and a Network Quality page showing latency, packet-loss readings and availability, queues and 60-second trends. Standard checks read local state; Deep checks send test requests only after confirmation. - Windows tray with a status badge, TUN and system-proxy switches, and background notifications for a reconnect lasting five seconds, a connection error, and recovery after a reported interruption; single-instance activation, start on boot, close-to-tray, a remembered window position and keyboard shortcuts. **Ctrl+1–4** selects pages, **Ctrl+S** applies changes, and **F5** refreshes VPN Gate or diagnostics. See [tray and keyboard controls](docs/INSTALLATION.md#tray-and-keyboard-controls). Android Quick Settings tile, launcher shortcuts, boot recovery and TV navigation. Twenty-one languages, with light and dark themes. - Consumer WARP Secret export to a file you choose, after confirmation. Usque cannot import that file to restore the account after reinstalling. Android **Per-app proxy** applies to the whole app, across accounts. When off, all apps use the VPN. When on, only selected apps do; newly installed apps must be selected. With Android **Block connections without VPN**, unselected apps are blocked instead of bypassing the tunnel. ## Privacy and limits - Usque requires the WARP server's public key to match the registered key. There is no option to skip this check. Credentials stay in Windows Credential Manager or Android Keystore. Windows uses a separate Agent for privileged network operations; Android runs the VPN in a dedicated process. - Proxies listen on loopback by default. SOCKS5 and HTTP support optional username/password authentication; without configured credentials they require no authentication. Proxy-only mode does not provide a system-wide VPN Kill Switch. - Diagnostics are generated locally and redacted. There is no usage analytics or automatic upload, and quality history stays in memory. Logs default to INFO and are limited to 7 days or 20 MiB. Do not post credentials or raw diagnostic bundles in public Issues; report vulnerabilities through [SECURITY.md](SECURITY.md). - Android's in-app Kill Switch cannot protect traffic after the VPN process dies. VPN Gate terminal failures also end the connection. To keep apps blocked after the VPN ends, enable both system **Always-on VPN** and **Block connections without VPN**. See [Android setup](docs/INSTALLATION.md#android-and-android-tv). - Usque does not combine several paths for extra bandwidth. Some quality readings, including HTTP/2 packet loss and PMTU, are unavailable. Local diagnostics cannot detect traffic leaks. ### DNS privacy Country-based and custom-domain direct rules use **Current network DNS** by default: matching domain queries go to the DNS servers on your current network, outside the VPN. You can instead choose **DoH** with a full HTTPS URL or **DoT** with a server name and port. New drafts prefill Cloudflare; saved custom settings are preserved. That resolver receives the queries; connection failures do not switch them to plaintext DNS. See [configuration steps and examples](docs/encrypted-direct-dns.md). Other remote VPN queries use the WARP tunnel or the selected final chain exit. HTTP/SOCKS5 chain DNS defaults to verified Cloudflare® DoH through that proxy; custom or non-default inherited DNS retains TCP DNS. With these exits, application-selected UDP/53 queries use TCP to that resolver, with no physical DNS fallback. See the [chain DNS choices](docs/CHAIN_PROXY.md#http-and-socks5-exits--http-与-socks5-出口). Apps that use their own encrypted DNS hide domain names from Usque, so direct routing uses IP rules. Rule downloads also respect Android Lockdown and any remaining Windows Kill Switch while disconnected. ### Experimental and unsupported features [Zero Trust enrollment](docs/ZERO_TRUST_EXPERIMENTAL.md) is experimental. It uses an organization identity for the MASQUE Internet tunnel and does not provide full Cloudflare One™ Client compatibility. macOS source is retained but not built or released. iOS, store distribution and a public CLI are outside this release's scope. ## Default network settings | Setting | Default | | --- | --- | | Consumer endpoint selection | Automatic selection; existing configurations retain Custom | | Saved custom endpoint IPv4 | `162.159.198.2` | | Saved custom endpoint IPv6 | `2606:4700:103::2` | | Port / SNI | `443` / `speed.cloudflare.com` | | Transport | Auto: HTTP/3, then HTTP/2 | | HTTP/3 congestion control | `cubic`; BBRv2, experimental BBRv3, and `reno` are selectable | | QUIC UDP receive buffer | [2 MiB target](docs/UDP_RECEIVE_BUFFER.md) on Windows/Android for H3 and L4; actual capacity is OS-dependent | | TUN MTU | `1280` | | Fallback DNS | `1.1.1.1`, `2606:4700:4700::1111` | | SOCKS5 | `127.0.0.1:1080`, `[::1]:1080` | | HTTP proxy | `127.0.0.1:8080`, `[::1]:8080` | Proxy address and port edits are drafts until applied. Proxy DNS uses the current exit by default: configure [WARP DNS](docs/WARP_DNS.md) in Advanced settings or the final DNS in the chain configuration. The Proxy page has no DNS settings; a proxy DNS choice saved by an older version keeps working. Advanced settings reset loads defaults into the draft; it does not apply them immediately. Zero Trust endpoint addresses start with registered values. In Advanced network settings, choose **Edit Zero Trust endpoints**, read the red fullscreen warning and acknowledge the risks and your authorization before editing IPv4/IPv6; then **Apply changes**. Reset stages the registered addresses; signing in again restores them and removes custom addresses. Home keeps a risk notice visible while the selected account has custom Zero Trust addresses or a running ZT session still uses them; the notice cannot be dismissed. In Advanced network settings, Automatic selection races eligible account endpoints; Custom keeps manual addresses. Port and SNI remain editable. See [automatic endpoints](docs/NETWORK_SETTINGS.md#automatic-endpoints--自动选择端点). Congestion-control changes are saved for the next manual connection or retry, not applied to the current session or its automatic reconnections. HTTP/2 uses system TCP. See [HTTP/3 congestion control](docs/congestion-control.md). ## Documentation and development Start with the [Wiki](https://github.com/GeorgeXie2333/usque-app/wiki/Home) for setup and practical tutorials. Use the [documentation index](docs/README.md) for the complete reference; most technical documents are in English. | Need | Read | | --- | --- | | Install, update, uninstall, or recover | [Installation](docs/INSTALLATION.md) | | Native Proton guest/account setup | [Proton VPN guide and current limits](docs/PROTON_VPN.md) | | Connect to Proton VPN through the WARP tunnel | [WireGuard over MASQUE tutorial](https://github.com/GeorgeXie2333/usque-app/wiki/Proton-VPN-over-MASQUE) | | Understand local quality checks | [Network Doctor](docs/network-doctor.md) | | Build and test changes safely | [Contributing](CONTRIBUTING.md) | | Understand implementation and verification status | [Implementation](docs/IMPLEMENTATION.md) | | Maintain an official release | [Release process](docs/RELEASE.md) | Use the pinned toolchains and change-scoped checks in the contribution guide. Compile-only builds and deterministic tests are safe workstation checks; installing development packages or exercising VPN lifecycle requires the designated isolated environments. ## Upstream and license Protocol behavior follows [Diniboy1123/usque](https://github.com/Diniboy1123/usque). This repository keeps a snapshot of that client in `oracle/go` for interoperability tests. The Flutter UI and Rust engine are new code. Upstream copyright stays in the license. First-party source is [MIT](LICENSE.md). Third-party components keep their own licenses. The optional [chain proxy](docs/CHAIN_PROXY.md) embeds OpenVPN 3 Core under MPL-2.0 and Mbed TLS under Apache-2.0. Corresponding source, reviewed patches and license texts are included in `third_party`; the application exposes the notices from its VPN Gate page. WireGuard uses BoringTun 0.7.1 (BSD-3-Clause), and local SVG icons use flutter_svg 2.3.0 (MIT); their notices are in the app's license registry. The independent Proton SRP implementation references Proton go-srp (MIT); its [copyright and full license](apps/usque_gui/assets/licenses/proton-srp.txt) are retained in source, test vectors and the app license registry. --- Cloudflare, WARP and Cloudflare One are trademarks and/or registered trademarks of Cloudflare, Inc. in the United States and other jurisdictions.