GeorgeXie2333/usque-app

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

Usque is an unofficial client compatible with Cloudflare® WARP® services for Windows and Android / Android TV. It combines a system VPN, SOCKS5, and HTTP proxy in a native Flutter interface, powered by a Rust MASQUE engine.

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.

Windows

Android

English interface previews rendered from the current source, shown disconnected.

These development docs prepare v0.3.1; application metadata and the release workflow now target v0.3.1 / 0.3.1+25. The v0.3.1 readiness review records checks and remaining requirements. For published packages, use GitHub Releases and documentation at the matching tag. The planned package set has six installers, plus two Windows MSI files used only by in-app updates:

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 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 for upgrades, uninstall, recovery, and Android developer-verification details, and Code signing for official identities. Updates require confirmation before downloading and use the platform installer; there is no unattended installation.

Upgrading from v0.3.0 migrates configuration from schema 23 to 24, which v0.3.0 and older clients cannot read. Review configuration compatibility and any required pre-upgrade backup before upgrading; reinstalling an older package does not reverse the migration.

1. Install a verified official package and open Usque.
2. Complete the first-run permissions and terms steps. Android requires VPN consent to finish setup; granting it may disconnect another VPN but does not start a Usque connection. Notifications are optional. 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 → TUN and local proxies on Windows, or Proxy → VPN and local proxies on Android, choose the outputs, then connect from Home. These switches take effect immediately; listener form edits require Apply changes. Proxy-only operation does not use the granted VPN permission to start a VPN.

VPN, SOCKS5 and HTTP are enabled by default; Windows system proxy is off. They share one WARP connection and can run together. Disabling all outputs keeps the transport connection but stops providing these application connection options. Each account stores its own credentials; only one account connects at a time. Network settings are shared by all accounts.

• Optional chain proxy: open Proxy → Chain proxy for OpenVPN, WireGuard, WARP via WireGuard, VPN Gate, HTTP, and SOCKS5, in that order. 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 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.
• Full-tunnel VPN, tunneled DNS, Kill Switch, LAN access and DIRECT/REJECT/PROXY routing rules with Ads. Custom domains and CIDRs support more-specific exceptions; conflicts are checked before saving.
• Custom WARP exit DNS: 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 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. 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.

• 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.
• 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.
• Usque does not combine several paths for extra bandwidth. Some quality readings, including HTTP/2 packet loss and PMTU, are unavailable. A local diagnostic pass does not establish that no traffic leaked or that performance improved.

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.

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. 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.

Zero Trust enrollment 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.

Proxy address and port edits are drafts until applied. Proxy DNS uses the current exit by default: configure WARP DNS 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.

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.

Start with the Wiki for setup and practical tutorials. Use the documentation index for the complete reference; most technical documents are in English.

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. A successful build is not installation, leak, or performance evidence.

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.

First-party source is MIT. Third-party components keep their own licenses. The optional chain proxy 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.

Cloudflare, WARP and Cloudflare One are trademarks and/or registered trademarks of Cloudflare, Inc. in the United States and other jurisdictions.