# Hysteria 2 from HyNetworks: a QUIC proxy for lossy links and censored networks > Hysteria 2 is a Go proxy built on a customized QUIC stack, with SOCKS5, HTTP proxy, TCP/UDP forwarding, Linux TProxy and TUN modes. This review covers what the repository documents, how to build and run it, and where it stops being the right tool. **HyNetworks/hysteria** — Hysteria is powerful, lightning-fast, and censorship-resistant open-source proxy software - Repository: https://github.com/HyNetworks/hysteria - Website: https://hysteria.network/ - Stars: 22,595 · Forks: 2,261 - Language: Go - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/hynetworks-hysteria ## What Hysteria 2 actually solves, and for whom Most proxy software assumes the path between client and server is roughly stable. Hysteria 2 is built for the case where it is not. The README describes it as "powerful, lightning-fast, and censorship-resistant" and says it is "designed to deliver unparalleled performance over unreliable and lossy networks." That is the design target: links with packet loss, jitter, or deliberate interference. The second problem is detection. The README states that "the protocol masquerades as standard HTTP/3 traffic, making it very difficult for censors to detect and block without widespread collateral damage." A censor that blocks it indiscriminately also blocks ordinary HTTP/3 traffic. That is a different threat model from a protocol that is merely encrypted. The audience follows from those two properties. It is for people running their own endpoint on a server they control, and for engineers who want a single binary that can expose SOCKS5, an HTTP proxy, TCP/UDP forwarding, Linux TProxy or a TUN device. It is not aimed at someone who wants to install a client, pick a provider from a list, and never touch a config file. ## The QUIC core, the masquerade, and the modes around it The repository is split into three Go modules: app/, core/ and extras/, tied together by go.work at the top level. core/ holds the protocol implementation; app/ holds the runnable binary and the mode implementations; extras/ holds optional pieces. PROTOCOL.md sits at the repository root, which is where the wire format is specified rather than in the README. The transport is a customized QUIC stack, not stock QUIC. That matters because the masquerade claim depends on the handshake being indistinguishable from HTTP/3 at the level a middlebox inspects. The README lists the modes as SOCKS5, HTTP Proxy, TCP/UDP Forwarding, Linux TProxy and TUN. Those are not separate binaries. They are modes of the same client, which is why the project describes itself as a "jack of all trades": one process can serve a local SOCKS5 port for applications and a TUN device for traffic that does not speak SOCKS. Authentication is pluggable. The README refers to "built-in support for custom authentication, traffic statistics & access control," which is the part that matters if you are running this for more than yourself. The extras/ directory and the test dependencies in pyproject.toml point at an HTTP auth server example: flask is listed there for "extras/auth HTTP auth test server." So the intended integration path is an HTTP endpoint the proxy calls, not a static password list baked into the config. The platform story is narrower than the feature list suggests. Linux TProxy is a Linux kernel feature, so that mode is Linux only. TUN needs a tun device, which on desktop platforms means elevated privileges. The README says there are "builds for every major platform and architecture" and platforms.txt exists in the repository, but the README does not enumerate which mode works where. That gap is worth checking against the documentation site before you plan a deployment. ## Building Hysteria 2 from the repository The repository does not ship an install script in the README. It points to v2.hysteria.network for getting started, and the build path visible in the tree goes through hyperbole.py, a Python build script that requires Python 3.11 or newer according to pyproject.toml. The Dockerfile is the most concrete build recipe in the repository. It uses a multi-stage build: a golang:1-alpine builder stage and an alpine dist stage. GOPROXY is empty by default, and the file documents how to override it: ```dockerfile ARG GOPROXY="" ENV GOPROXY ${GOPROXY} ``` With the default empty value, the build resolves modules directly. The comment in the file gives the override form: docker build --build-arg GOPROXY="https://goproxy.io". If your build host cannot reach the module proxy directly, that argument is the documented escape hatch. The builder stage installs git, build-base, bash and python3, then runs the build script and moves the result: ```bash python hyperbole.py build -r mv ./build/hysteria-* /go/bin/hysteria ``` The -r flag is passed to hyperbole.py as shown in the Dockerfile. The dist stage installs bash, tzdata, ca-certificates, iptables and nftables, then copies the binary in and sets the entrypoint: ```dockerfile COPY --from=builder /go/bin/hysteria /usr/local/bin/hysteria ENTRYPOINT ["hysteria"] ``` The iptables and nftables packages are there because TProxy and TUN modes manipulate firewall rules. The comment in the Dockerfile notes that ca-certificates is installed "to ensure no CA certificate errors," which tells you the proxy is expected to make outbound TLS connections of its own. Once the image is built, the binary is the entrypoint, so arguments go straight to hysteria. The README does not document the flag set, and the repository does not include a sample client or server config. For the actual server and client configuration, the README defers to the documentation site at v2.hysteria.network, which also has a Chinese version at v2.hysteria.network/zh/. Treat that site as the source for config keys, not this repository. ## Where Hysteria 2 is the wrong choice The masquerade is the feature and the constraint. If the protocol looks like HTTP/3 to a middlebox, it also looks like HTTP/3 to your own tooling. Any monitoring or traffic-shaping device on your path that classifies by protocol will treat this as web traffic, and that is intentional, not a bug to be worked around. The bigger practical limitation is that Hysteria 2 is not a general-purpose protocol that other software speaks. The README mentions "a long list of 3rd party apps," but the protocol is specified in PROTOCOL.md by this project, and the client and server are the same codebase. If your requirement is that any standards-compliant client can connect, this is the wrong tool. WireGuard, OpenVPN or a plain TLS tunnel will interoperate with far more software. Linux TProxy mode is Linux-only by definition, and TUN mode needs device creation privileges. On a locked-down host where you cannot add a tun device or alter firewall rules, the Dockerfile's iptables and nftables packages will not help you; you are limited to the userspace modes like SOCKS5 and HTTP proxy. There is also a version boundary to respect. The README links Hysteria 1.x at v1.hysteria.network and labels it "legacy." Version 1 and version 2 configurations are not the same thing, and the documentation is split across two sites for that reason. Pasting a 1.x config into a 2.x binary is a failure mode the project's own structure warns about. Finally, the repository does not document rollback, downgrade behaviour, or what happens to a running proxy when the server is upgraded ahead of the client. The README is silent on that, and the release notes for the app/v2.12.x line are not reproduced in the README. If you run this in production, you are choosing the upgrade order yourself. ## How it compares to a plain TLS tunnel or WireGuard The closest comparison is not another proxy but the general-purpose VPN. WireGuard is a kernel-level tunnel with a small, fixed protocol. It is fast, it is auditable, and it does not try to look like anything else. On a clean network it will beat Hysteria 2 on overhead. On a lossy or actively interfered link, WireGuard has no mechanism to distinguish congestion loss from deliberate drops, and its traffic is trivially identifiable as WireGuard. Hysteria 2 takes the opposite position on both points. It runs in userspace over a customized QUIC stack, which costs CPU per byte compared to a kernel tunnel, and it spends that cost on two things: loss recovery tuned for unreliable paths, and a handshake that the README says "masquerades as standard HTTP/3 traffic." A censor blocking Hysteria 2 has to accept collateral damage to real HTTP/3. Against a plain TLS tunnel, the difference is the same trade in a different direction. A TLS tunnel is simple, widely understood, and easy to put behind a reverse proxy, but it is a stream over TCP, so head-of-line blocking applies and packet loss hurts every connection sharing the tunnel. Hysteria 2 multiplexes over QUIC, where a lost packet stalls only the stream that lost it. If your links are clean and your only goal is private connectivity between machines you own, WireGuard is the smaller dependency. If the path is bad or the network is hostile, the QUIC core and the HTTP/3 masquerade are the reason to pick Hysteria 2 instead. ## Maintenance, licensing and what an upgrade costs you The repository is not archived, and the last push was on 2026-09-16. The most recent release listed is app/v2.12.3, published on 2026-09-16, with app/v2.12.2 on 2026-08-23 and app/v2.12.1 on 2026-08-09 before it. That is a steady cadence across the 2.12 line. The licence is MIT, declared in LICENSE.md and shown as the MIT badge in the README. MIT is permissive: you can use, modify and redistribute the code, including in closed products, provided the copyright notice and permission notice are preserved. That is a summary of the licence text, not legal advice; read LICENSE.md itself if the distinction matters to your organisation. The upgrade cost is mostly configuration drift, not build complexity. The build is a single Python script invocation and a binary move, both of which are already written down in the Dockerfile. What changes between releases is the config surface, and the project keeps two documentation sites alive (v2.hysteria.network and v1.hysteria.network) precisely because the two major versions diverged. Pinning to a specific release tag and reading the release notes before moving is cheaper than discovering a renamed key in production. One thing the repository does not give you is a compatibility matrix for third-party clients. If you depend on a client you did not build, the release notes are the only place that would tell you about protocol changes, and the README does not summarise them. ## Conclusion Adopt Hysteria 2 if you control both ends of a link and either the network is lossy or you need a proxy that looks like HTTP/3 on the wire. Do not adopt it if you need a protocol with broad third-party interoperability, or if you cannot run a server outside the network you are crossing. Before committing, check three things in the repository itself: the mode you intend to use in the documentation at v2.hysteria.network, whether the current release line matches the config format you have, and whether the Go toolchain on your build host satisfies what go.work and the Dockerfile expect. The Dockerfile builds from a pinned golang:1-alpine image and copies the binary to /usr/local/bin/hysteria with ENTRYPOINT ["hysteria"], so a container deployment is the shortest path to a first run. ## FAQ ### How do I install Hysteria 2? The README does not give install steps; it links to the documentation at v2.hysteria.network for getting started. The repository itself contains a Dockerfile that builds the binary in a golang:1-alpine stage and copies it to /usr/local/bin/hysteria with ENTRYPOINT ["hysteria"], and a hyperbole.py build script invoked as python hyperbole.py build -r. The build script requires Python 3.11 or newer per pyproject.toml. ### How do I use Hysteria 2? The README does not document the command line or configuration keys; it defers to v2.hysteria.network, which also has a Chinese version. What the README does state is the set of modes the client supports: SOCKS5, HTTP Proxy, TCP/UDP Forwarding, Linux TProxy and TUN. ### What is Hysteria 2? Hysteria 2 is an open-source proxy written in Go, built on a customized QUIC protocol. The README describes it as censorship-resistant and says the protocol masquerades as standard HTTP/3 traffic. It is the successor to Hysteria 1.x, which the README labels legacy and documents at v1.hysteria.network. ### Which proxy modes does Hysteria 2 support? The README lists SOCKS5, HTTP Proxy, TCP/UDP Forwarding, Linux TProxy and TUN. Linux TProxy is a Linux kernel feature, so that mode is Linux-only, and TUN requires a tun device. The README says builds exist for every major platform and architecture but does not map modes to platforms. ### What licence does Hysteria 2 use? MIT, declared in LICENSE.md and shown as the MIT badge in the README. That permits use, modification and redistribution, including in closed products, as long as the copyright and permission notice are preserved. Read LICENSE.md for the exact terms. ## Sources - [HyNetworks/hysteria on GitHub](https://github.com/HyNetworks/hysteria) - [License: MIT](https://github.com/HyNetworks/hysteria/blob/master/LICENSE) - [Project website](https://hysteria.network/) - [README](https://github.com/HyNetworks/hysteria/blob/master/README.md) - [Releases](https://github.com/HyNetworks/hysteria/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hynetworks-hysteria