H UI: a Hysteria2 panel that manages the server, not the protocol

What H UI solves, and for whom

Hysteria2 ships as a server and a client. It does not ship a web interface for the people you hand accounts to. H UI fills that gap and nothing else: the README's own description is "Just the panel for Hysteria2". The project is for the operator of a Hysteria2 node who needs to create users, cap their traffic, see who is online right now, and hand each of them a subscription link, without editing YAML by hand for every change.

The feature list is operational rather than protocol-level. It covers limiting user traffic, showing online status, forcing users to log off, counting online users and resetting traffic; limiting how many devices a user can have online at once; user subscription links and node URLs; import and export of users; management of Hysteria2 configurations and Hysteria2 versions; port hopping; changing the web port and the Hysteria2 traffic multiplier; Telegram notification; and viewing, importing and exporting system and Hysteria2 logs. Interface languages are English and Simplified Chinese.

That scope tells you who it is not for. If you want a general proxy control plane that speaks several protocols, this is the wrong repository. If you want a client, the README points at the Hysteria2 third-party app list instead.

The mechanism: Gin, SQLite and a supervised Hysteria2 process

The dependency list in go.mod describes the architecture before any source file does. gin-gonic/gin provides the HTTP layer, gorm.io/gorm with github.com/glebarez/sqlite is the storage engine, golang-jwt/jwt handles session tokens, robfig/cron schedules recurring jobs, shirou/gopsutil reads host metrics, go-telegram-bot-api sends notifications, google/go-github/v39 is present for release lookups, and spf13/cobra builds the command line. There is no external database. State lives in a SQLite file under the data directory.

The repository layout separates concerns in the usual Go web shape: controller, dao, middleware, model, router, service and util at the top level, with cmd for the CLI entry point and proxy for the code that deals with the Hysteria2 process itself. That proxy package is the interesting one, because it is what turns a panel into something that can start, stop and reconfigure a Hysteria2 instance and report its state back to the UI.

Resource claims in the README are modest: 256MB of memory or more, x86_64/amd64 or arm64/aarch64, CentOS 8+, Ubuntu 20+ or Debian 11+. The Dockerfile is alpine:3.15 and installs bash, tzdata, ca-certificates and nftables, which is consistent with the panel needing to touch firewall rules for port hopping. The README does not document the internal API surface, so anything beyond the UI is undocumented territory.

Installing H UI and creating your first user

The README calls the shell script the recommended path. It downloads the latest release and sets the service up for you. The script accepts an optional version argument, so the second form pins a specific release from the releases page.

bash <(curl -fsSL https://raw.githubusercontent.com/jonssonyan/h-ui/main/install.sh)

bash <(curl -fsSL https://raw.githubusercontent.com/jonssonyan/h-ui/main/install.sh) v0.0.1

After an automatic installation the README states that the login username and password are a random six characters, and the connection password is the username, a dot, then the password. Open the panel on port 8081 and log in with those. Only the system administrator can log in, so there is no separate user-facing login page.

If you prefer Docker, the compose file in the repository pins the image, adds NET_ADMIN, uses host networking and mounts four host directories for binaries, data, exports and logs.

services:
  h-ui:
    image: jonssonyan/h-ui
    cap_add:
      - NET_ADMIN
    container_name: h-ui
    restart: always
    network_mode: host
    volumes:
      - /h-ui/bin:/h-ui/bin
      - /h-ui/data:/h-ui/data
      - /h-ui/export:/h-ui/export
      - /h-ui/logs:/h-ui/logs
    environment:
      TZ: Asia/Shanghai

The equivalent one-liner from the README is below. The -p flag changes the web port, which defaults to 8081.

docker run -d --cap-add=NET_ADMIN \
  --name h-ui --restart always \
  --network=host \
  -e TZ=Asia/Shanghai \
  -v /h-ui/bin:/h-ui/bin \
  -v /h-ui/data:/h-ui/data \
  -v /h-ui/export:/h-ui/export \
  -v /h-ui/logs:/h-ui/logs \
  jonssonyan/h-ui \
  ./h-ui -p 8081

Once the panel is up, the first real task is creating a user and copying that user's subscription link out of the management view, then importing the link into one of the Hysteria2 clients listed at v2.hysteria.network. The README does not walk through the user-creation form, so expect to read the interface rather than the documentation at this point.

Where H UI stops and you have to take over

The upgrade procedure is the clearest limitation. The README's System Upgrade section says to export the user, system configuration and Hysteria2 configuration from the management background, redeploy the latest version of h-ui, and import the data back afterwards. There is no in-place upgrade command, no schema migration tool mentioned, and no rollback procedure. If an import fails after you have replaced the binary, the README does not describe how to get back to the previous state. Treat the export as the only copy that matters and keep it off the host.

Manual installation is the second rough edge. The README gives sysadmin/sysadmin as the default login and connection password, and then notes that only the system administrator can log in. Anyone who follows the systemd instructions without changing that pair is running a panel with published credentials on port 8081. The automatic installer avoids this by generating random credentials, which is a good reason to prefer it.

The Docker path needs NET_ADMIN and host networking. That is a real privilege grant, and it means the container is not isolated from the host network namespace. Port hopping and the nftables package in the image explain why, but it is still a trade-off worth naming rather than glossing over.

Finally, the README does not document an HTTP API or a CLI for user management. Everything goes through the web interface, which makes scripting or configuration-as-code awkward.

How H UI differs from 3x-ui and S-ui

The related searches around this project are full of 3x-ui and S-ui comparisons, and the difference is scope. 3x-ui is a multi-protocol panel: it manages several inbound types behind one interface, so its data model has to be generic across protocols. H UI is single-protocol by design, which is why its feature list can talk about Hysteria2 traffic multipliers, port hopping and Hysteria2 version management as first-class controls rather than protocol-specific plugins.

S-ui sits in a similar place, a panel oriented around a specific modern proxy stack rather than a broad protocol matrix. The practical distinction for H UI is the storage and deployment shape: a single Go binary with SQLite, four mounted directories in Docker, and no external database to run alongside it. That makes it cheap to host on a small VPS, and it also means your entire user database is one file you are responsible for backing up.

If your node already runs several protocols and you want one console for all of them, H UI will not fit; it will only manage the Hysteria2 side. If your node is Hysteria2 and nothing else, the narrower model is the reason the UI can expose things a generic panel would treat as advanced options.

Licence and the cost of keeping it running

H UI is GPL-3.0. If you deploy it unmodified for your own users, the ordinary obligations apply: keep the licence and notices intact and make the source available to people who receive the software. If you fork it, add proprietary modules, or ship a modified binary to customers, the copyleft terms reach the derivative work. That is a decision for your own legal review, not something this article can settle, but the practical point is that H UI is not a permissive-licence component you can quietly embed.

The maintenance cost is mostly operational. The README recommends a scheduled reboot as a performance measure, with a crontab line for 04:00, which is a sign that long-running instances are expected to accumulate state. It also points at TCP Brutal as the recommended network accelerator, alongside teddysun/across and two Linux-NetSpeed repositories. Those are external projects with their own upgrade cycles.

On the project itself, the most recent release listed is v0.0.25 from 2026-07-20, and the last push to the repository was on 2026-08-16. Version numbers are still in the 0.0.x range, so expect breaking changes between releases and read the release notes before upgrading rather than assuming compatibility.

Editorial conclusion

Adopt H UI if you already run Hysteria2 and want per-user traffic quotas, online-device caps, forced logoff and subscription links from one Go binary with SQLite underneath, and if you are comfortable with a manual export-and-import upgrade. Do not adopt it if you want the panel to install and manage the Hysteria2 server for you, or if you cannot accept a GPL-3.0 derivative work. Before deploying, confirm which Hysteria2 version the current release manages, check that port 8081 and the SSH forwarded port 8082 are free, and read docs/FAQ.md, since the README defers there for the questions it does not answer.

Frequently asked questions

Official sources

1. jonssonyan/h-ui on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases