---
title: "Hysteria 2"
description: "The Hysteria 2 options, TLS settings, links and features Potatso supports."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.potatso.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hysteria 2

A Hysteria 2 server is described by a **password** and its **TLS settings**, and optionally by **obfuscation** and **port hopping**. Hysteria 2 runs over QUIC, the UDP-based protocol behind HTTP/3, so it keeps up its speed on networks that lose packets. Potatso connects to a server when it supports the server's settings. Use the tables below to check your server's settings, as shown by your provider or in its `hysteria2://` link.

You can add a Hysteria 2 server by hand, with a [`hysteria2://` or `hy2://` link](#links), or by importing:

- a Clash or Mihomo subscription,
- an Xray configuration,
- a Surge configuration.

Potatso doesn't import Hysteria 2 servers from a sing-box configuration yet. Use the server's `hysteria2://` link instead.

## Authentication {#authentication}

| Server's authentication | Supported |
| --- | --- |
| A password (`auth.type: password`) | ✅ |
| A user name and password (`auth.type: userpass`) | ✅ Enter them as one password: `name:password` |
| An HTTP or command authenticator | ✅ Enter the password it expects |

A wrong password doesn't connect. Many servers show an ordinary website (their masquerade) to anyone without the password.

## Obfuscation {#obfuscation}

| Obfuscation | Clash key | Link parameter | Supported |
| --- | --- | --- | --- |
| None | | | ✅ |
| Salamander | `obfs: salamander`, `obfs-password` | `obfs=salamander`, `obfs-password` | ✅ |
| Gecko | `obfs: gecko` | `obfs=gecko` | ❌ |

Salamander scrambles every packet so the connection doesn't look like QUIC. The password must match the server's. Set it as **Salamander Password** in the server's settings. Leave it empty for a server without obfuscation.

Potatso doesn't import a server that uses Gecko obfuscation, since it couldn't connect to it.

## Bandwidth {#bandwidth}

| Setting | Clash key | Supported |
| --- | --- | --- |
| Download bandwidth | `down` | ✅ The server sends to you at this rate |
| Upload bandwidth | `up` | ❌ Potatso uploads with BBR congestion control and ignores this setting |
| Congestion control | `congestion` in the official client | ❌ Always BBR |

When you set a **download bandwidth**, such as `100 Mbps`, the server sends at that rate even when packets are lost, using Hysteria's Brutal congestion control. Set it close to your real download speed: too high and the connection gets slower, not faster. Leave it empty and the server adapts its rate itself.

Bandwidth takes a number with a unit (`bps`, `Kbps`, `Mbps`, `Gbps`), or a plain number in Mbps.

## Port hopping {#port-hopping}

A server with port hopping listens on a range of UDP ports, and Potatso moves between them every so often. This helps on networks that slow down or block one UDP port after a while.

| Setting | Clash key | Supported |
| --- | --- | --- |
| Ports | `ports` | ✅ A range like `20000-30000`, a list like `443,8443`, or both |
| Hop interval | `hop-interval` | ✅ In seconds, 30 by default and 5 at least. A range like `10-30` picks a random interval. |

Set them as **Port Hopping** and **Hop Interval** in the server's settings. The server's port is then only used for the first connection.

## TLS {#tls}

| Setting | Clash key | Link parameter | Supported |
| --- | --- | --- | --- |
| Server name (SNI) | `sni` | `sni`, `peer` | ✅ Without one, Potatso uses the server's address. |
| Skip certificate verification | `skip-cert-verify` | `insecure` | ✅ |
| Certificate pinning (SHA-256) | `fingerprint` | `pinSHA256` | ✅ |
| ALPN | `alpn` | `alpn` | ✅ `h3` only, which Potatso always uses |
| Custom CA certificate | `ca` in the official client | | ❌ |
| TLS client certificate | `certificate`, `private-key` | | ❌ |
| Encrypted Client Hello (ECH) | `ech-opts` | `ech` | ❌ |
| Verify against another name | `name-cert-verify` | | ❌ |

Turning off certificate verification lets anyone between you and the server read your traffic. Many Hysteria 2 servers use a self-signed certificate: pin it instead. Set the SHA-256 of the server's certificate as the certificate pin. With a pin, Potatso trusts that certificate and no other, whatever its name.

Potatso doesn't import a server that needs one of the unsupported settings above, since it would connect without it and the server wouldn't answer.

## UDP {#udp}

Hysteria 2 carries UDP in QUIC datagrams, over the same connection as TCP. UDP is on by default. Turn off UDP Relay in the server's settings only if your server has UDP turned off (`disableUDP`).

Through an Xray server, UDP packets larger than about 1,100 bytes arrive damaged. This is a bug in Xray's Hysteria 2 server. The official server, sing-box and mihomo relay every size.

## Feature support {#features}

| Feature | Supported |
| --- | --- |
| [Hysteria 2 protocol](https://v2.hysteria.network/docs/developers/Protocol/): HTTP/3 authentication, TCP streams | ✅ |
| UDP in QUIC datagrams, including large packets split in fragments | ✅ |
| Many connections in one QUIC connection | ✅ |
| Salamander obfuscation | ✅ |
| Gecko obfuscation | ❌ |
| [Download bandwidth](#bandwidth) (Brutal on the server) | ✅ |
| Upload bandwidth (Brutal from your device) | ❌ |
| [Port hopping](#port-hopping) | ✅ |
| Fast open (one round trip less per connection) | ✅ Always on |
| Certificate pinning, skip certificate verification | ✅ |
| ECH, custom CA, TLS client certificates | ❌ |
| Realms (connecting through a rendezvous server) | ❌ |
| Fake TCP (`mimic`) | ❌ |
| Custom QUIC flow-control windows, `cwnd`, `udp-mtu` | ❌ |
| `hysteria2://` and `hy2://` links | ✅ |

Every supported feature is tested against at least one real Hysteria 2 server: the [official server](https://v2.hysteria.network/), [sing-box](https://sing-box.sagernet.org/), [mihomo](https://wiki.metacubex.one/) or [Xray](https://xtls.github.io/).

Some features of the official Hysteria client are settings of its own program, and Potatso does the same job its own way:

- Routing and ACLs: use rules in your profile.
- Local SOCKS5 and HTTP servers, forwarding and TUN mode: Potatso captures your device's traffic itself.
- Lazy connection: Potatso connects when traffic needs the server.

Server-side settings, such as the masquerade website, the speed test or the server's own bandwidth limits, need nothing on your device.

## `hysteria2://` links {#links}

A `hysteria2://` link holds a whole server in one line. `hy2://` is the same link with a shorter name.

```text
hysteria2://password@host:port/?parameters#name
```

| Part | Description |
| --- | --- |
| `password` | The password, percent-encoded. For a user name and password, write `name:password`. |
| `host` | Server address. Put an IPv6 address in square brackets, such as `[2001:db8::1]`. |
| `port` | Server port. When it's missing, Potatso uses 443. For [port hopping](#port-hopping), list the ports here, such as `443,20000-30000`. |
| `name` | Optional. The server's name in Potatso. |

The parameters follow the [official format](https://v2.hysteria.network/docs/developers/URI-Scheme/):

| Parameter | Description |
| --- | --- |
| `sni` | The TLS server name. |
| `insecure` | `1` turns off certificate verification. |
| `pinSHA256` | The SHA-256 of the server's certificate. |
| `obfs`, `obfs-password` | `salamander` and its password. |
| `mport` | Port hopping ports, as some apps write them instead of in the port. |
| `hop-interval` | The hop interval in seconds. |
| `up`, `down` | The upload and download bandwidth, as some apps write them. |

Potatso doesn't import a link with `obfs=gecko` or `ech`. It doesn't import `hysteria2+realm://` links either.

When Potatso shares a Hysteria 2 server, it offers a `hysteria2://` link, with the hopping ports either in the port or as `mport`.

### Examples {#link-examples}

Each example shows the link to import. The password is `secret`.

A basic server:

```text
hysteria2://secret@hy2.example.com:443/?sni=hy2.example.com#Basic
```

Salamander obfuscation with the password `hidden`:

```text
hysteria2://secret@hy2.example.com:443/?obfs=salamander&obfs-password=hidden#Salamander
```

Port hopping between 20000 and 30000:

```text
hysteria2://secret@hy2.example.com:443,20000-30000/?sni=hy2.example.com#Hopping
```

A self-signed certificate, pinned:

```text
hysteria2://secret@203.0.113.7:443/?sni=hy2.example.com&pinSHA256=abababababababababababababababababababababababababababababababab#Pinned
```

Source: https://docs.potatso.com/protocols/hysteria2/index.mdx