An overview of Hysteria2 server setup and client connections

In my VPN comparison article, I mentioned Hysteria2 as one of the strongest candidates for China-facing connectivity. This post summarizes how to actually set it up and connect to it. It is an overview rather than a full step-by-step guide.

What Hysteria2 is

Hysteria2 is a proxy protocol built on QUIC, which means it uses UDP and can move faster than TCP in many cases. It also uses its own congestion control mode, Brutal, to make aggressive use of the line.

Key points:

It blends into QUIC / HTTP/3 style traffic
It is UDP-based and often faster than TCP-based VPNs
It uses custom congestion control for throughput
Configuration is relatively simple because it is YAML-based

One important note: Hysteria 1.x and Hysteria2 are not protocol-compatible. Make sure the client is explicitly for version 2.

Server setup overview

Requirements

A Linux VPS
Open ports: TCP/80, TCP/443, and UDP/443
An SSL certificate, either Let’s Encrypt or self-signed

Installation

Recommended official installer:

bash <(curl -fsSL https://get.hy2.sh/)

This registers a systemd service. You still need to prepare the config manually.

There is also an official Docker image, tobyxdd/hysteria, which is convenient if you prefer Docker Compose management.

Config file

Put a file like this at /etc/hysteria/config.yaml:

listen: :443

tls:
  cert: /path/to/cert.pem
  key: /path/to/key.pem

auth:
  type: password
  password: your-secret-password

masquerade:
  type: proxy
  proxy:
    url: https://www.bing.com
    rewriteHost: true

The masquerade section is important because it makes the server look like a normal HTTPS endpoint instead of an obvious Hysteria server.

Management panels

Direct config editing is the basic workflow, but if you want a GUI:

Blitz for user management, traffic monitoring, and Telegram bot integration
H-UI for a simpler web UI

Client apps

Using an existing client is the easiest option.

Windows, macOS, Linux

App	Notes
v2rayN	Multi-platform and feature-rich
Hiddify	Free, open source, multi-platform
NekoRay	GUI client built with Qt

For v2rayN, choose the sing-box core. The Xray core will not handle Hysteria2.

Android

App	Notes
Hiddify	Recommended, free, no ads
NekoBox	APK from GitHub, Play Store versions are unofficial

iOS

App	Notes
Hiddify	Free
Shadowrocket	Paid, about $3
Streisand	Free

How to connect

Clients usually accept one of these:

A URI such as hy2://password@server:443?sni=example.com
A subscription URL issued by the server side
Manual input of server, port, and password

Building your own app

If you want to integrate Hysteria2 into your own software, there are a few practical paths.

Go

The official implementation is apernet/hysteria:

go get github.com/apernet/hysteria/core/v2

sing-box

sing-box supports many protocols including Hysteria2.

Supports VLESS, Trojan, Shadowsocks, and more
Requires Go 1.21+
Uses JSON or TOML configuration

This is the realistic choice if your app needs to support multiple protocols.

Python

There is also a Python package, hysteria2, which wraps the Go implementation. It is useful if you want to script around Hysteria2 from Python.

Mobile apps

For iOS or Android apps, the practical approaches are:

call sing-box through an FFI layer
use an existing engine such as VPNclient Engine, which combines Swift or Kotlin with a Go or C++ backend

Because TUN handling differs by OS, forking an existing client is often more realistic than starting from zero.