Hysteria Core Use Cases: 9 Ideal Scenarios for High-Performance QUIC Proxy

Hysteria core excels in high-throughput, low-latency proxy deployments, censorship-resistant networking that mimics HTTP/3 traffic, and embedded Go applications requiring unified TCP and UDP transport over a single QUIC connection.

The apernet/hysteria repository provides a production-grade proxy engine built on QUIC that can operate as a standalone binary or embedded library. Understanding these Hysteria core use cases enables developers to leverage custom congestion control, protocol obfuscation, and fine-grained traffic management for challenging network environments ranging from congested mobile links to heavily filtered corporate networks.

High-Throughput Proxying on Unreliable Networks

Hysteria core is optimized for scenarios where traditional TCP proxies struggle with packet loss and variable latency. In core/client/client.go and core/server/server.go, the engine wraps raw UDP sockets in a quic.Transport with datagram support enabled, allowing it to operate at full line speed even on congested or lossy connections.

Custom Congestion Control Selection

The implementation supports multiple congestion algorithms including BBR and Cubic. During the authentication handshake, the server in core/server/server.go (lines 61‑80) decides whether to use a configured algorithm (UseConfigured) or apply a brute-force bandwidth limit (UseBrutal) based on the client’s advertised capacity. The client mirrors this logic in core/client/client.go (lines 44‑58), ensuring both endpoints optimize for the actual network conditions.

Censorship-Resistant Traffic Deployment

Hysteria core use cases prominently include circumventing network filters where deep packet inspection (DPI) blocks standard proxy protocols. The engine masquerades as ordinary HTTP/3 traffic, making it indistinguishable from legitimate web browsing.

HTTP/3 Authentication Handshake

The protocol hides authentication behind a standard POST /auth request. The client sends custom HTTP/3 headers (Hysteria-Auth, Hysteria-CC-RX, Hysteria-Padding) as shown in core/client/client.go (lines 44‑68). The server validates these via the configured authenticator—supporting password, user-pass, HTTP, or command-based methods—and replies with status code 233 (HyOK), as implemented in core/server/server.go (lines 44‑70).

Salamander Obfuscation

For environments requiring additional camouflage, the optional "Salamander" obfuscator encrypts QUIC packets using a BLAKE2b-256 based XOR stream with a pre-shared key. When obfs.type = salamander is configured, app/cmd/server.go (lines 15‑33) wraps the raw net.PacketConn using obfs.WrapPacketConn before passing it to the QUIC transport, as detailed in extras/obfs/salamander.go.

Unified TCP and UDP Relay

Unlike traditional proxies that require separate sockets for TCP and UDP, Hysteria transports both protocols over a single QUIC connection, eliminating NAT traversal complications.

Datagram Support and Session Management

By setting EnableDatagrams: true in the QUIC configuration, the core enables unreliable datagrams for UDP while maintaining reliable streams for TCP. In core/client/client.go (lines 64‑66), a udpSessionManager handles UDP session creation, while core/server/server.go (lines 98‑110) parses incoming datagrams using protocol.ParseUDPMessage and routes them through the outbound chain. This design supports fragmentation required by QUIC’s datagram size limits.

Transparent Proxy and Infrastructure Integration

Hysteria core supports Linux-specific transparent proxying modes that allow traffic redirection without modifying client application configurations.

TPROXY and Realm Support

The server can operate in "realm" mode for UDP hole-punching and NAT traversal, or integrate with Linux TPROXY for iptables-based redirection. Configuration parsing in app/cmd/server.go demonstrates realm handling and UDP port redirection logic. The extras/correctnet/correctnet.go utility manages UDP port redirection specifics, while extras/realm/realm.go provides peer-to-peer NAT traversal capabilities essential for TUN mode deployments.

Embedded Go Library Integration

One of the most powerful Hysteria core use cases involves direct embedding into existing Go services rather than using external binaries.

Native API Consumption

The core exposes a plain Go API through NewServer and NewClient functions defined in core/server/server.go and core/client/client.go respectively. Configuration structs in core/server/config.go and core/client/config.go allow programmatic setup of TLS, authentication, bandwidth limits, and outbound chains. This enables developers to integrate high-performance proxying directly into microservices, edge nodes, or custom networking tools without shelling out to external processes.

Fine-Grained Traffic Management

ACL-Based Access Control

The built-in ACL engine supports filtering by IP, domain, GeoIP, and GeoSite data, and can be chained in front of any outbound (direct, SOCKS5, HTTP). The extras/outbounds/acl.go file implements parsing and matching logic, while app/cmd/server.go (lines 87‑126) demonstrates how outbounds are constructed using fillOutboundConfig, optionally inserting a resolver before the ACL for domain-based rules.

Bandwidth Throttling and Statistics

Both client and server enforce bandwidth caps. The client-side TX limiting logic resides in core/client/client.go, while core/server/server.go (lines 92‑100) integrates optional TrafficLogger implementations that record per-connection byte counts and can trigger disconnections when limits are exceeded.

Advanced Protocol Inspection

The server supports a request hook (sniffer) mechanism that inspects the first few bytes of TCP streams before establishing outbound connections. This enables TLS SNI hijacking or protocol detection, implemented in extras/sniff/sniff.go and configured via fillRequestHook in app/cmd/server.go (lines 65‑70). Additionally, extras/masq/masq.go provides HTTP masquerading capabilities, allowing the server to present as a standard web server, reverse proxy, or static file server when not handling Hysteria traffic.

Implementation Examples

Minimal Embedded Server

package main

import (
	"log"
	"time"

	"github.com/apernet/hysteria/core/v2/server"
	"github.com/apernet/hysteria/extras/v2/auth"
)

func main() {
	cfg := &server.Config{
		Conn:          mustListenUDP(":443"),
		TLSConfig:     server.TLSConfig{Certificates: loadTLSCert()},
		Authenticator: &auth.PasswordAuthenticator{Password: "secret"},
		Outbound:      server.NewDirectOutboundSimple(server.DirectOutboundModeAuto),
		BandwidthConfig: server.BandwidthConfig{
			MaxTx: 100 * 1024 * 1024, // 100 MiB/s
			MaxRx: 50 * 1024 * 1024,  // 50 MiB/s
		},
		QUICConfig: server.QUICConfig{
			InitialStreamReceiveWindow: 4 << 20,
			MaxStreamReceiveWindow:     4 << 20,
			MaxIdleTimeout:            30 * time.Second,
		},
	}
	s, err := server.NewServer(cfg)
	if err != nil {
		log.Fatalf("create server: %v", err)
	}
	log.Println("Hysteria server listening …")
	if err := s.Serve(); err != nil {
		log.Fatalf("serve: %v", err)
	}
}

func mustListenUDP(addr string) net.PacketConn {
	pc, err := net.ListenPacket("udp", addr)
	if err != nil {
		panic(err)
	}
	return pc
}

Key files referenced: core/server/config.go, core/server/server.go, extras/auth/password.go.

Minimal Embedded Client

package main

import (
	"fmt"
	"log"

	"github.com/apernet/hysteria/core/v2/client"
)

func main() {
	cfg := &client.Config{
		ServerAddr:      "example.com:443",
		TLSConfig:       client.TLSConfig{InsecureSkipVerify: true},
		Auth:            "secret",
		BandwidthConfig: client.BandWidthConfig{MaxTx: 0}, // Let server decide
		QUICConfig: client.QUICConfig{
			EnableDatagrams: true,
		},
	}
	c, info, err := client.NewClient(cfg)
	if err != nil {
		log.Fatalf("connect: %v", err)
	}
	defer c.Close()
	fmt.Printf("Connected – UDP enabled: %v, Tx limit: %d\n", info.UDPEnabled, info.Tx)

	// Example TCP forward
	conn, err := c.TCP("tcp.example.com:80")
	if err != nil {
		log.Fatalf("TCP: %v", err)
	}
	defer conn.Close()
	fmt.Fprintf(conn, "GET / HTTP/1.0\r\n\r\n")
	buf := make([]byte, 4096)
	n, _ := conn.Read(buf)
	fmt.Println(string(buf[:n]))
}

Key files referenced: core/client/client.go, core/client/config.go.

Adding SOCKS5 Outbound

func makeServerWithSOCKS5() *server.Config {
	return &server.Config{
		Conn:      mustListenUDP(":443"),
		TLSConfig: server.TLSConfig{Certificates: loadTLSCert()},
		Authenticator: &auth.PasswordAuthenticator{Password: "secret"},
		Outbound: server.NewPluggableOutboundAdapter(
			outbounds.NewSOCKS5Outbound("127.0.0.1:1080", "", ""),
		),
	}
}

Key files referenced: extras/outbounds/socks5.go, app/cmd/server.go.

Summary

• Hysteria core delivers a compact, QUIC-based proxy engine suitable for high-throughput, low-latency applications on unreliable networks.
• Censorship resistance is achieved through HTTP/3 traffic masquerading, Salamander obfuscation, and hidden authentication mechanisms.
• Unified transport handles TCP streams and UDP datagrams over a single QUIC connection, simplifying NAT traversal.
• Embedding capabilities allow direct integration into Go programs via NewServer and NewClient APIs without external dependencies.
• Advanced features include fine-grained ACLs, bandwidth throttling, traffic statistics, and protocol sniffing for SNI hijacking.

Frequently Asked Questions

What makes Hysteria core different from standard QUIC implementations?

Hysteria core implements a custom authentication handshake that masquerades as HTTP/3 traffic and supports configurable congestion control algorithms (BBR, Cubic, or Brutal) selected dynamically based on bandwidth availability. According to the source code in core/client/client.go and core/server/server.go, it also provides unified TCP and UDP handling over QUIC datagrams, which standard QUIC libraries do not automatically provide in a proxy context.

Can Hysteria core be used as a library in existing Go applications?

Yes. The core is designed as a plain Go library exposing NewClient and NewServer functions in core/client/client.go and core/server/server.go respectively. You can embed it directly into existing services by importing the packages and configuring client.Config or server.Config structs, eliminating the need to manage external proxy processes.

How does the Salamander obfuscation work?

Salamander obfuscation, implemented in extras/obfs/salamander.go, encrypts QUIC packets using a BLAKE2b-256 based XOR stream with a pre-shared key. When enabled via configuration, app/cmd/server.go wraps the raw UDP connection with obfs.WrapPacketConn before passing it to the QUIC transport, making the traffic patterns indistinguishable from random noise to passive observers while remaining compatible with the Hysteria protocol.

Is Hysteria core suitable for transparent proxying with iptables?

Yes. The server supports Linux TPROXY integration for transparent traffic redirection, requiring no client application configuration changes. The extras/correctnet/correctnet.go utility handles UDP port redirection specifics, while extras/realm/realm.go provides UDP hole-punching capabilities for TUN mode deployments, as configured in app/cmd/server.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}