Hiddify-Manager: a multi-user anti-censorship panel with more than 20 protocols

What Hiddify-Manager is for, and who runs it

Hiddify-Manager is a server-side control panel. It is not the client you install on a laptop or phone; the README lists separate Hiddify applications for those, and this repository is the multi-user panel that those clients connect to. The stated purpose is a multi-user panel with an installation the project calls effortless, supporting more than 20 protocols including Reality and a Telegram proxy, with the README saying it is optimized for censorship circumvention in China, Russia and Iran.

The audience follows from that. Someone who needs one tunnel for one device has no reason to run MariaDB, Redis and a Flask panel. The panel makes sense when one operator hands out credentials to a group: a family, a small organization, a community, or a service provider reselling access. The multi-user part is the point, not a side effect. If you only ever connect from your own machine, the extra moving parts are cost with no return.

The README also states the panel is listed by Xray in its installation section, which is the closest thing to a third-party signal in the repository. Everything else about quality is the project describing itself.

Xray and SingBox side by side, with a Flask panel in front

The architecture visible in the repository is three layers. At the bottom, the repository ships a Dockerfile based on ubuntu:24.04 that installs python3 and ca-certificates, creates /opt/hiddify-manager/data, and then runs scripts/common/hiddify_installer.sh with the arguments docker --no-gui --no-log. That installer is what lays down the actual proxy cores and their configuration; the README names both Xray and SingBox as the multiple cores the panel drives.

In the middle sits the panel application itself. The Makefile shows a debug target that stops the hiddify-panel systemd unit and runs Flask from services/hiddify-panel/src/ with FLASK_APP=wsgi.py, pointing HIDDIFY_CFG_PATH at /opt/hiddify-manager/data/hiddify-panel/app.cfg and serving on port 9000. So the panel is a Flask application with its own configuration file under the data directory, and in normal operation it is managed as a system service rather than run by hand.

On top, docker-compose.yml wires the panel to two supporting services. MariaDB runs with MYSQL_DATABASE set to hiddifypanel and MYSQL_USER set to hiddifypanel, with MARIADB_RANDOM_ROOT_PASSWORD set to 1. Redis runs with a password passed through REDIS_PASSWORD and a command that starts redis-server with --requirepass. Both expose their ports only on 127.0.0.1, and both define health checks that the panel waits on through depends_on with condition: service_healthy. The panel container itself declares network_mode: host, privileged: true and cap_add NET_ADMIN, which is the honest admission that a proxy panel needs to touch the host network directly.

One detail in the Dockerfile matters for operators: HIDDIFY_DISABLE_UPDATE is set to true and DOCKER_MODE to true. Inside the container, the panel is told not to update itself. That is a sensible split, since self-updating software in a container fights the image lifecycle, but it also means the automatic update feature the README advertises is not the mechanism that keeps a Docker deployment current.

Installing Hiddify-Manager with Docker and reaching the panel

The repository provides docker-compose.yml, so the Docker path is the one you can follow from the files alone. Clone the repository, create a docker.env file next to the compose file (the compose file references ./docker.env through env_file, and docker.env is a top-level entry in the repository), then bring the stack up. The panel container builds from the repository root because the service sets build: .

git clone https://github.com/hiddify/hiddify-manager.git
cd hiddify-manager
docker compose up -d

The build runs the Ubuntu-based Dockerfile, which executes the installer without the GUI and without logging, so expect a long first build rather than a quick pull. When the containers are healthy, the panel is reachable on the host ports that the compose file publishes.

ports:
  - "80:80"
  - "443:443"

Those two ports are the first real constraint. If anything else on the host already listens on 80 or 443, the stack will not come up cleanly, and because the panel container uses network_mode: host, the mapping behaves differently from a normal bridged container. The compose file also mounts ./docker-data/ to /opt/hiddify-manager/data/, which is where the panel keeps its state; MariaDB and Redis keep theirs under ./docker-data/mariadb_data and ./docker-data/redis_data.

If you prefer a pinned image over a local build, the compose file shows the alternative in comments: ghcr.io/hiddify/hiddify-manager:latest, :beta, :dev, or a version tag such as ghcr.io/hiddify/hiddify-manager:v10.80.0. Comment out the build line and uncomment the image line you want. The README does not document a rollback procedure for a failed upgrade, so treat the data volume as the thing you back up rather than assuming the panel can undo a bad image swap.

Where Hiddify-Manager is the wrong tool

The clearest limitation is scope. This is a panel, and a panel assumes a server you administer. People search for Hiddify for Windows, Hiddify Android and an APK, and none of those come from this repository. If your goal is a client on your own device, you are looking at the wrong project, and installing this on a VPS will not give you a Windows or Android application.

The second limitation is operational weight. MariaDB and Redis are not optional in the compose file; the panel declares depends_on for both with healthy conditions, so a failure in either backing service stops the panel from starting. For a handful of users, that is a lot of infrastructure to keep alive, patch and back up. The README advertises automatic backup every 6 hours, but the README does not say where those backups land or how to restore them, and the compose file does not mount a separate backup destination, so the backups live inside the same volume tree as the data they protect unless you arrange otherwise.

The third is the privileged container. privileged: true plus NET_ADMIN plus host networking means the panel container has broad access to the host. That is a design consequence of running proxy cores that need to bind ports and manipulate networking, not an oversight, but it changes the threat model: a compromise in the panel is close to a compromise of the host. If that trade is unacceptable, a plain Xray configuration managed by hand or by a configuration management tool is the more conservative choice.

Finally, the installer writes to /opt/hiddify-manager. The Makefile explicitly refuses to run its build and apply targets when the working directory is already /opt/hiddify-manager or /opt/hiddify-config, printing a message telling you to clone the repository outside that folder. That is a guard against clobbering a live installation, and it tells you the installer is not idempotent in the way you might assume.

How it differs from a hand-written Xray or SingBox configuration

The obvious alternative is running the cores directly. Xray and SingBox are the engines underneath, and the README lists Xray as the project that lists Hiddify-Manager in its installation section, so the relationship is layered rather than competitive. A hand-written setup is a JSON or YAML configuration file per core, a systemd unit, and your own user management, which for two or three people is a text file and a reload command.

The difference in approach is where the complexity sits. With a raw configuration, adding a protocol means editing the core's config and restarting it; adding a user means generating keys and adding an inbound entry. Hiddify-Manager moves that into a web panel backed by a database, which is why MariaDB is in the compose file: users, their protocols and their quotas are rows, not file edits. The panel also generates client-side subscription links, which is the feature that makes it usable for a group, since you can hand someone a link instead of walking them through a configuration file.

That trade cuts both ways. You gain a UI, per-user accounting and a single place to add protocols. You lose the ability to read the whole configuration in one sitting, and you inherit a Python application, a database and a cache as part of your attack surface. For a single operator with a handful of users, the raw configuration is smaller and easier to reason about. For someone distributing access to dozens of people across several protocols, the panel earns its dependencies.

Licence, upgrades and the maintenance you are signing up for

Hiddify-Manager is GPL-3.0. If you run it as a service for yourself or your group, the licence mostly means you receive the source and can modify it. If you redistribute a modified version, or offer a modified version as a network service, the copyleft terms are the part to read carefully, and the panel's web interface makes the network-service question more relevant than it would be for a library. This is a description of the licence, not legal advice; check the GPL-3.0 text and your own situation.

The upgrade story differs by deployment method. In the Docker path, the Dockerfile sets HIDDIFY_DISABLE_UPDATE=true, so the panel's own update mechanism is off and upgrades happen by rebuilding or by pulling a new image tag. In a native installation, the README advertises automatic update as a feature, which means the panel will change underneath you. The repository's default branch is dev, and the Makefile's latest-tags target distinguishes stable tags matching vX.Y.Z from beta tags matching vX.Y.Zb or vX.Y.Z.dev, which tells you both kinds are published and that picking one is a deliberate decision.

The recent releases are v12.3.3, v12.3.2 and v12.3.1, published on 2026-05-29, 2026-05-29 and 2026-05-26. The last push to the repository was on 2026-09-21. The README says backups run every 6 hours, but it does not document a restore path, so the upgrade cost you should budget for is the time to verify that a backup can actually be restored before you rely on it.

Editorial conclusion

Adopt Hiddify-Manager if you are running a shared access service for many users on a Linux host and you want Xray and SingBox behind one panel with scheduled backups. Do not adopt it if you need a single-user client, a Windows or Android endpoint, or a stack you can audit line by line, because the installer writes into /opt/hiddify-manager and takes over ports 80 and 443. Before deploying, read the docker-compose.yml and confirm the data volume path, the MariaDB and Redis health checks, and whether the image you intend to run is the latest tag or a pinned version.

Frequently asked questions

Official sources

1. hiddify/Hiddify-Manager on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases