QUIC is the point, so UDP quality decides the fit
Hysteria 2 is a proxy for TCP and UDP traffic built on a customized QUIC transport. Its client can expose SOCKS5 and HTTP proxy listeners, forward ports, create a TUN interface, or work through Linux TProxy. The project targets unreliable and lossy networks, where its congestion-control choices may behave differently from a conventional TCP proxy. If the path blocks UDP, none of that matters because the connection cannot use its intended transport.
The protocol can masquerade as standard HTTP/3 traffic. A server may proxy an ordinary website so HTTP requests receive plausible content instead of revealing an empty endpoint. The official guide says this section can be removed where censorship is irrelevant, in which case HTTP requests receive a 404 response. Masquerade is one piece of deployment behavior, not a promise that every filtering system will treat the traffic identically.
A public server needs a domain, TLS, and one UDP port
The recommended setup starts with a server that has a public IPv4 or IPv6 address and a domain pointing to it. A YAML file selects the listening address, authentication, certificate path or ACME settings, and optional masquerade target. Password authentication is the short example, while the README also names custom authentication, traffic statistics, and access control as integration points. Realms is the documented alternative when a server sits behind NAT without a public address.
Port 443 is the default. On Linux, the guide recommends granting cap_net_bind_service to the binary or running it with enough privilege to bind that port. The ACME example needs a domain and email address; the manual TLS path needs a certificate and private key. Firewall and provider rules must allow UDP on the chosen port.
What happened when we ran it
Our sandbox classified the detected environment as Python, installed 33 packages in 15 seconds, and left 36 MB on disk. The build completed successfully in 7 seconds. GitHub identifies Go as the repository's primary language, so the two classifications do not agree. The supplied lab log does not explain why. We are reporting both facts instead of turning the mismatch into a theory.
The harness found no test script or target, so it skipped tests. That means there is no passing or failing test count for this review. Pip-audit reported 0 known vulnerabilities among the 33 installed Python packages. The checkout contained 312 files, roughly 40,152 lines of source, and 15.8 MB of repository data. It also had 8 CI workflow files and a Dockerfile, but no tests directory.
Those results cover commit 619a6f8 in a fresh unprivileged Debian container with 3 CPUs and 8 GB of RAM. We did not operate a public Hysteria server, measure proxy speed, test censorship resistance, or compare congestion controllers.
Bandwidth and TLS values can make a valid config unsafe
The client guide asks for a server address, authentication value, bandwidth settings, and local listeners. It says higher bandwidth figures can backfire when they exceed the network's real capacity, producing congestion and unstable connections. Hysteria can use Brutal, BBR, or Reno congestion control; removing the bandwidth section selects the configured non-Brutal controller, with BBR as the documented default under the standard profile.
TLS deserves equal attention. A client using a private certificate can trust a supplied CA file. The alternative insecure: true disables verification, and the guide warns against using it alone because it permits interception. Adding pinSHA256 binds the connection to a certificate fingerprint. Sharing the generated connection URI also shares the password and settings inside it, so treat that URI as a credential rather than a harmless server address.
Issue 1656 shows how a QUIC timeout can hide an MTU error
Open issue 1656 documents an Android LTE path with MTU 1300 where a 1,280-byte QUIC payload became a 1,308-byte IPv4 packet. The local socket returned EMSGSIZE, and no packet left the phone, yet the client showed only a timeout about no recent network activity. The reporter reproduced the condition in an isolated Linux namespace and separated it from server failure or network filtering.
That report matters because generic timeouts encourage the wrong diagnosis. A user may change servers, certificates, or obfuscation while the local route cannot send the initial datagram. It is one open report against a particular commit and configuration, not proof that all low-MTU routes fail. Operators testing cellular or nested-tunnel paths should capture packets on both ends and inspect local socket errors before blaming censorship or the remote host.
Issue 1365 covers a different mobile concern. One Samsung Fold 6 user reported disconnection after about a minute idle and a 5 to 10 second reconnect after waking, despite disabling battery optimization in two client apps. The same report says an iPhone did not show the problem. Since third-party apps and operating-system behavior are involved, the issue does not isolate Hysteria itself. It does establish that background notification delivery needs device-specific testing.
Version 2.12.2 is current, with an active multilingual tracker
GitHub now resolves the requested apernet/hysteria path to HyNetworks/hysteria. It recorded 22,383 stars, 253 combined issues and pull requests, and a last push on August 23, 2026. Release app/v2.12.2 shipped the same day with a stateless-reset switch, Unix-socket support for masquerade proxy mode, and an IPv6 fix for mimic mode. Issue updates continued on August 24 in both Chinese and English.
Hysteria 2 earns a trial when a conventional proxy performs poorly on a lossy route and UDP remains usable. Its official documentation is detailed enough to expose the tradeoffs around certificates, bandwidth, masquerade, and privileges. The missing lab test target keeps us from giving the checkout a clean test verdict. Run it on the exact networks and phones that matter, because QUIC behavior is inseparable from their MTU, filtering, sleep policy, and UDP quality.