hy2scale

README

HY2 SCALE

Hysteria 2 mesh relay network with a web management UI.
Route traffic through any node, run VPN services, manage everything from a browser.

English | 中文 | 한국어

---

See the Wiki for full installation, configuration, and API documentation.

Quick Start

One-liner (native binary, systemd)

curl -fsSL https://raw.githubusercontent.com/FrankoonG/hy2scale/main/install.sh | sudo sh

Auto-detects the CPU architecture (amd64, arm64, armv7, mips64le, mipsle-softfloat), downloads the matching tarball from the latest release, installs the binary to /usr/local/bin/hy2scale, and registers a systemd service. Re-running upgrades in place. Pin a version with HY2SCALE_VERSION=v1.3.3; uninstall with … | sudo sh -s -- --uninstall.

Docker

Full mode (host network — everything enabled):

docker run -d --name hy2scale \
  --network host --privileged \
  -v hy2scale-data:/data \
  --restart unless-stopped \
  frankoong/hy2scale:latest

Bridge mode (VPN + proxies, no routing rules):

docker run -d --name hy2scale \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device-cgroup-rule="c 10:200 rwm" \
  --device-cgroup-rule="c 108:0 rwm" \
  -p 5565:5565/tcp -p 5565:5565/udp \
  -p 500:500/udp -p 4500:4500/udp -p 1701:1701/udp -p 51820:51820/udp \
  -v hy2scale-data:/data \
  --restart unless-stopped \
  frankoong/hy2scale:latest

The two --device-cgroup-rule lines grant access to /dev/net/tun (relay packet capture) and /dev/ppp (L2TP/IPsec PPP layer). Without c 108:0 rwm, L2TP tunnels establish IKE+ESP successfully but pppd exits before assigning an IP, so clients see "Connected" briefly then disconnect. Full mode skips this because --privileged grants every device.

Open http://<host>:5565/scale/ — default login admin / admin.

For iKuai v4, download the .ipkg from Releases and install via the app store — see the iKuai v4 guide.

Features

• Connect nodes into a mesh and route traffic through any of them.
• See live topology and latency in an interactive graph or a table view.
• Run VPN / proxy services: Hysteria 2, SOCKS5, HTTP, Shadowsocks, L2TP, IKEv2, WireGuard.
• Per-user exit routing, traffic limits, expiry, bulk management.
• IP and domain routing rules steer specific traffic through specific exits.
• TLS certificate management with built-in CA signing.
• Multi-IP peer aggregation (failover or bandwidth bonding).
• Backup / restore, in-place binary upgrade (manual or one-click online check), UI in EN / 中文 / 한국어.
• Select-to-edit UX: pick a row in any list and a top-right Edit button drives editing; clicking blank area outside the list clears the single selection; hysteria2:// share URLs can be imported by long-pressing + Add Node.

Screenshots

Topology graph and list view, showing a Singapore home node peering with remote nodes across several regions:

Building

git clone https://github.com/FrankoonG/hy2scale.git
cd hy2scale
docker build -t hy2scale .

Star History