简体中文

Usque is an unofficial GUI client for consumer Cloudflare WARP. Flutter draws the UI. A Rust engine handles MASQUE, CONNECT-IP, DNS, proxies, and connection state. There is no WebView.

Usque is an independent project. It is not affiliated with, sponsored by, or endorsed by Cloudflare. Cloudflare and WARP are trademarks of Cloudflare, Inc. Use of consumer WARP remains subject to Cloudflare's terms and privacy policy.

Windows

Android

The v0.2.1 tag on main builds and checks these six packages:

macOS source is in the tree but is not built or released. This release does not include iOS, production-supported Zero Trust, store listings, a public CLI, or multipath bandwidth aggregation. Source builds expose an experimental, release-gated Zero Trust organization enrollment described below.

• Consumer WARP registration, WARP License Key registration, and confirmed Consumer WARP Secret export.
• Experimental Cloudflare Zero Trust device enrollment on Windows and Android, limited to using an organization identity with the existing MASQUE Internet tunnel.
• VPN, SOCKS5, HTTP proxy, and Windows system proxy can run together on one MASQUE channel.
• HTTP/3 over QUIC, falling back to HTTP/2 over TLS, with IPv4/IPv6 Happy Eyeballs for the physical path.
• Full-tunnel VPN, tunneled DNS, Kill Switch, LAN access, and custom CIDR bypass rules.
• Optional country-based direct routing with separately downloaded per-country GeoIP data and one verified global V2Fly GeoSite catalog. SOCKS5/HTTP, Android VPN, and Windows TUN classify GeoSite names before DNS and use GeoIP when no QNAME is available; unknown destinations stay on MASQUE.
• SOCKS5 TCP/UDP and HTTP CONNECT/forward; listeners default to loopback.
• Several profiles, one active at a time, with identity stored per profile.
• Android per-app proxy (include-only): when off, every app uses the VPN; when on, only selected apps do. Newly installed apps stay off the tunnel until selected.
• Android Quick Settings tile, launcher shortcuts, boot recovery, and TV navigation.
• Windows tray, single-instance activation, start on boot, and close-to-tray.
• Local redacted diagnostics. No analytics, telemetry, or automatic upload.

Choosing an IPv4 or IPv6 MASQUE endpoint only picks the physical ingress. Either path can carry IPv4 and IPv6 inside CONNECT-IP. Usque keeps one active transport; it does not add bandwidth across paths.

When direct-country routing is enabled, GeoSite-matched domain queries use the DNS servers of the selected physical network and are visible to that DNS provider. Other domain queries keep using the configured WARP DNS through MASQUE. Applications using DoH or DoT hide the QNAME from Usque, so those flows can only be classified by GeoIP. GEO rule downloads are allowed while disconnected, but never bypass Android Lockdown or a surviving Windows Kill Switch.

These values can be changed and reset. A non-loopback proxy listener has no password and always shows a warning.

Download Usque from the GitHub Releases page. Prefer the APK that matches the device ABI. The universal APK includes ARMv8, x64, and ARMv7 libraries and is larger; use it when the architecture is unknown. GitHub shows a SHA-256 for each asset; compare that digest and the published signer fingerprint before installing.

• Pre-1.0 Windows packages use a fixed self-signed identity. Check the published SHA-256 and certificate fingerprint before accepting the OS warning.
• Pre-1.0 Android packages use a project-controlled self-signed certificate and are not on Google Play. You may need a manual install or ADB.
• A later v1.0.0 signing change will be its own release.
• The release workflow compiles, signs, and checks architecture, checksums, SBOMs, and provenance. It does not attach those extras to the GitHub Release, and it does not install packages on real devices or run long VPN tests.
• Usque never installs updates by itself. Optional update checks only open the release page.
• Windows uninstall asks for confirmation in Settings, restores Usque-owned network state, and can delete the current user's local data if you ask.

See Installation and removal for verification, upgrades, uninstall, and recovery.

One profile can enable several outputs. They share one pinned MASQUE transport and a packet multiplexer.

Windows defaults to VPN/TUN + SOCKS5 + HTTP, with the system proxy off. Android defaults to VPN + SOCKS5 + HTTP. Per-app proxy is an Android app setting, not part of a Profile: when it is on, only selected apps use the VPN. You can turn every output off and leave only the transport up.

• Endpoint pinning is always on. The GUI has no insecure TLS mode.
• Secrets, private keys, tokens, device identifiers, licenses, and endpoint pins go in Windows Credential Manager or Android Keystore.
• Secret export is explicit, confirmed, and written only to a path you pick.
• The Windows engine runs unprivileged. A small Agent owns TUN, routes, DNS, firewall, and system-proxy state.
• Android uses VpnService and an isolated :vpn process.
• Logs default to INFO and stop at 7 days or 20 MiB.

Read SECURITY.md before reporting a vulnerability. Do not put credentials or raw diagnostics in a public Issue. Official package signatures are described in the code signing policy.

The tree pins Rust 1.97.1, Flutter 3.44.7, Android NDK 29.0.14206865, and the packaging tools. CONTRIBUTING.md has setup, checks, safety limits, and pull request rules.

Progress is in Implementation. The experimental scope and live-tenant release gate are in Zero Trust experimental support. Signing and the release workflow are in Release process.

Protocol behavior follows 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.

Source is MIT. Third-party components keep their own licenses.