apernet/hysteria-website: The Proxy Protocol Waging War on Network Entropy

How a custom QUIC implementation and behavioral mimicry turned a personal project into a high-speed lane through state-level censorship.

8 min read • View on GitHub • More from apernet

An armored steam train painted to look like a civilian cargo car smashing through a brick barricade. — Hysteria combines unstoppable brute-force momentum with a deceptive exterior to bypass active network filtering.

It was originally a project I developed for myself when I was in college. China’s global Internet connectivity has been notoriously bad for as long as I can remember (still not any better right now). Not just in the sense of censorship, but also in terms of connection quality.

Toby, Lead Developer of Hysteria · Interview with Xeovo Hub

Key Takeaways

Hysteria abandons standard TCP congestion control in favor of a Brutal QUIC implementation that ignores packet loss to maintain high throughput.
The protocol employs Salamander obfuscation to eliminate packet patterns and defeat entropy-based deep packet inspection.
Hysteria can masquerade as a legitimate HTTP/3 web server by serving real content from other sites to deflect active probes.
The project documentation relies on a sophisticated MkDocs i18n pipeline to maintain complex technical configurations across four languages.

The Politeness Trap

Standard internet protocols are designed to be polite. When a network connection drops packets, standard congestion control algorithms like BBR or Reno assume the network is crowded. They immediately cut their transmission rate in half to share the limited bandwidth. State-level censors exploit this politeness.

By intentionally dropping a small percentage of packets on international links, firewalls can force polite protocols into a crawl. This renders standard VPNs and proxies nearly useless for high-bandwidth tasks. Hysteria simply stops being polite.

Built on a custom implementation of QUIC (RFC 9000), Hysteria uses a congestion control algorithm aptly named Brutal. Instead of backing off when packets disappear, Brutal maintains a fixed, aggressive transmission rate. It brute-forces its payload through lossy links to guarantee throughput.

How standard TCP congestion control fails on lossy networks compared to Hysteria's fixed-rate Brutal algorithm.

The Salamander and the Masquerade

Speed attracts attention. Aggressive network behavior usually triggers deep packet inspection (DPI) blocks. Firewalls look for specific cryptographic handshakes or measure the entropy of the data stream to identify unauthorized proxy traffic.

Hysteria defends itself with two layers of behavioral mimicry. The first is Salamander obfuscation. Unlike standard proxies that merely encrypt payloads, Salamander converts packets into seemingly random bytes with absolutely no discernible pattern. This defeats entropy-based detection.

The second layer is the Masquerade feature. If a censor actively probes the Hysteria server's IP address, the proxy acts as a reverse proxy for a legitimate site. It will silently fetch and return a functioning website (like Hacker News), making the server indistinguishable from a standard HTTP/3 web server.

A close-up of a chameleon resting on a dense printed circuit board, its skin perfectly replicating the metallic traces. — Salamander obfuscation and HTTP/3 masquerading allow Hysteria to blend seamlessly into normal web traffic.

Feature	Legacy Proxies (e.g., Shadowsocks)	Hysteria 2
Transport Protocol	TCP	Custom QUIC (UDP)
Congestion Control	Standard (Slows on packet loss)	Brutal (Ignores packet loss)
Obfuscation	Passive Encryption	Salamander (Patternless Noise)
Active Probing Defense	Vulnerable	HTTP/3 Masquerade (Reverse Proxy)

Forging the Weapon

Hysteria was born out of frustration with poor international routing. Eight years ago, before the QUIC standard existed, lead developer Toby built a custom reliable transmission protocol based on UDP in Java called Dragonite.

A stipple-drawn portrait of Toby, lead developer of Hysteria.

As the QUIC standard matured, the project evolved into Hysteria. It shifted from a personal script for watching YouTube into a robust Go-based protocol with an ecosystem of third-party management panels like Blitz.

Structuring the Resistance

The apernet/hysteria-website repository is the multi-lingual instruction manual for this complex tool. Built with MkDocs Material, it uses a sophisticated internationalization pipeline.

The mkdocs-static-i18n plugin maps highly technical documentation concerning Port Hopping, ACLs, and TPROXY routing across English, Chinese, Russian, and Persian. It redefines the navigation tree for each locale to ensure precise technical localization.

A complex blueprint of a mechanical engine being translated by four distinct mechanical printing presses. — The MkDocs i18n build pipeline renders a single complex technical truth for different global audiences.

The documentation site presents a stark contrast in tone. It pairs hardcore network engineering concepts with randomized Hall of Fame contributor lists and playful anime mascot branding. It is a highly polished, community-driven interface for a tool designed to subvert state-level network control.