Skip to content

Hysteria 2 client setup

This document records how to install the Hysteria 2 client, start it with a local client config, and verify that the local HTTP/SOCKS5 proxies are working.

Client config path

Use a private local config file, for example:

/Users/euwang/hysteria2-client.yaml

Example client config shape:

server: azure.example.com:443
auth: YOUR_HYSTERIA2_PASSWORD

socks5:
    listen: 127.0.0.1:1080

http:
    listen: 127.0.0.1:8080

Do not commit the real config file if it contains auth or other secrets.

Install on macOS

Option 1: Homebrew

brew install hysteria

Verify the binary:

which hysteria
hysteria version

Option 2: manual install

Use this only if Homebrew is not available or if a specific binary is needed.

For Apple Silicon Mac:

curl -L -o /tmp/hysteria \
  https://download.hysteria.network/app/latest/hysteria-darwin-arm64
chmod +x /tmp/hysteria
sudo mv /tmp/hysteria /usr/local/bin/hysteria

For Intel Mac:

curl -L -o /tmp/hysteria \
  https://download.hysteria.network/app/latest/hysteria-darwin-amd64
chmod +x /tmp/hysteria
sudo mv /tmp/hysteria /usr/local/bin/hysteria

Verify:

hysteria version

Install on Ubuntu

Option 1: official install script

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

Verify:

which hysteria
hysteria version

Option 2: manual install

For most x86_64 Ubuntu VPS or desktop machines:

curl -L -o /tmp/hysteria \
  https://download.hysteria.network/app/latest/hysteria-linux-amd64
chmod +x /tmp/hysteria
sudo mv /tmp/hysteria /usr/local/bin/hysteria

For ARM64 Ubuntu:

curl -L -o /tmp/hysteria \
  https://download.hysteria.network/app/latest/hysteria-linux-arm64
chmod +x /tmp/hysteria
sudo mv /tmp/hysteria /usr/local/bin/hysteria

Verify:

hysteria version

Start the client

On macOS, using the local config path:

hysteria client -c /Users/euwang/hysteria2-client.yaml

On Ubuntu, using a typical config path:

hysteria client -c ~/.config/hysteria/client.yaml

If the config is valid and the server is reachable, the client should print logs showing that it connected to the server and started local proxy listeners.

Example successful connected log

euwang@MBP ~ % hysteria client -c /Users/euwang/hysteria2-client.yaml
2026-06-08T15:30:38+08:00   INFO    client mode
2026-06-08T15:30:39+08:00   INFO    connected to server {"addr": "192.11.1.128:443", "udpEnabled": true, "tx": 125000000, "count": 1}
2026-06-08T15:30:39+08:00   INFO    HTTP proxy server listening {"addr": "127.0.0.1:8080"}
2026-06-08T15:30:39+08:00   INFO    SOCKS5 server listening {"addr": "127.0.0.1:1080"}
2026-06-08T15:30:39+08:00   INFO    update available    {"version": "v2.9.2", "url": "https://github.com/apernet/hysteria/releases", "urgent": true}

Test the connection

Keep the Hysteria client running in one terminal. Open another terminal and test the local SOCKS5 proxy:

curl --socks5-hostname 127.0.0.1:1080 https://ipinfo.io/ip

Test the local HTTP proxy:

curl -x http://127.0.0.1:8080 https://ipinfo.io/ip

Both commands should return the public IP of the Hysteria server, not the local machine's normal public IP.

To compare with the direct local network path:

curl https://ipinfo.io/ip

If the proxied IP and direct IP are different, traffic is going through the Hysteria client.

Check local listening ports

On macOS or Ubuntu:

lsof -nP -iTCP:1080 -sTCP:LISTEN
lsof -nP -iTCP:8080 -sTCP:LISTEN

Expected result: the hysteria process should be listening on 127.0.0.1:1080 and 127.0.0.1:8080.

Debug failed connections

Run the client with debug logging:

hysteria client -c /Users/euwang/hysteria2-client.yaml --log-level debug

Common failure points:

  • failed to parse config: YAML syntax error or unsupported field.
  • authentication failed: wrong auth value.
  • TLS handshake failed: certificate, SNI, or server-domain mismatch.
  • connection refused: server is not listening on the configured address or port.
  • i/o timeout: network path, firewall, UDP blocking, or server availability problem.

Optional: one-shot test script

Save this as ~/scripts/test-hysteria2-client.sh:

#!/usr/bin/env bash
set -euo pipefail

CONFIG="${1:-/Users/euwang/hysteria2-client.yaml}"

echo "1) Checking hysteria binary..."
command -v hysteria
hysteria version || true

echo
echo "2) Checking config file exists..."
test -f "$CONFIG"
echo "Config: $CONFIG"

echo
echo "3) Checking direct public IP..."
curl -fsS https://ipinfo.io/ip || true

echo
echo
echo "4) Start the client in another terminal:"
echo "hysteria client -c '$CONFIG'"
echo
echo "After it starts, press Enter here to test the local proxies."
read -r

echo
echo "5) Checking local listening ports..."
lsof -nP -iTCP:1080 -sTCP:LISTEN || true
lsof -nP -iTCP:8080 -sTCP:LISTEN || true

echo
echo "6) Testing SOCKS5 proxy..."
curl -fsS --socks5-hostname 127.0.0.1:1080 https://ipinfo.io/ip

echo
echo
echo "7) Testing HTTP proxy..."
curl -fsS -x http://127.0.0.1:8080 https://ipinfo.io/ip

echo
echo
echo "Done. If the proxied IP is the Hysteria server IP, the client works."

Make it executable:

chmod +x ~/scripts/test-hysteria2-client.sh

Run it:

~/scripts/test-hysteria2-client.sh /Users/euwang/hysteria2-client.yaml