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

> Explore Hysteria core use cases for high-performance QUIC proxy. Discover scenarios for censorship resistance, low-latency, and unified TCP/UDP transport in embedded Go apps.

- Repository: [Aperture Internet Laboratory/hysteria](https://github.com/apernet/hysteria)
- Tags: use-cases
- Published: 2026-05-13

---

**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`](https://github.com/apernet/hysteria/blob/main/core/client/client.go) and [`core/server/server.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/core/client/client.go) (lines 64‑66), a `udpSessionManager` handles UDP session creation, while [`core/server/server.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/app/cmd/server.go) demonstrates realm handling and UDP port redirection logic. The [`extras/correctnet/correctnet.go`](https://github.com/apernet/hysteria/blob/main/extras/correctnet/correctnet.go) utility manages UDP port redirection specifics, while [`extras/realm/realm.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/core/server/server.go) and [`core/client/client.go`](https://github.com/apernet/hysteria/blob/main/core/client/client.go) respectively. Configuration structs in [`core/server/config.go`](https://github.com/apernet/hysteria/blob/main/core/server/config.go) and [`core/client/config.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/extras/outbounds/acl.go) file implements parsing and matching logic, while [`app/cmd/server.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/core/client/client.go), while [`core/server/server.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/extras/sniff/sniff.go) and configured via `fillRequestHook` in [`app/cmd/server.go`](https://github.com/apernet/hysteria/blob/main/app/cmd/server.go) (lines 65‑70). Additionally, [`extras/masq/masq.go`](https://github.com/apernet/hysteria/blob/main/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

```go
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`](https://github.com/apernet/hysteria/blob/main/core/server/config.go), [`core/server/server.go`](https://github.com/apernet/hysteria/blob/main/core/server/server.go), [`extras/auth/password.go`](https://github.com/apernet/hysteria/blob/main/extras/auth/password.go).

### Minimal Embedded Client

```go
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`](https://github.com/apernet/hysteria/blob/main/core/client/client.go), [`core/client/config.go`](https://github.com/apernet/hysteria/blob/main/core/client/config.go).

### Adding SOCKS5 Outbound

```go
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`](https://github.com/apernet/hysteria/blob/main/extras/outbounds/socks5.go), [`app/cmd/server.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/core/client/client.go) and [`core/server/server.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/core/client/client.go) and [`core/server/server.go`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/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`](https://github.com/apernet/hysteria/blob/main/extras/correctnet/correctnet.go) utility handles UDP port redirection specifics, while [`extras/realm/realm.go`](https://github.com/apernet/hysteria/blob/main/extras/realm/realm.go) provides UDP hole-punching capabilities for TUN mode deployments, as configured in [`app/cmd/server.go`](https://github.com/apernet/hysteria/blob/main/app/cmd/server.go).