3X-UI: A Multi-Protocol Xray Control Panel with Per-Client Quotas and Fail2ban
GitHub describes it as Xray panel supporting multi-protocol multi-user expire day & traffic & IP limit (Vmess, Vless, Trojan, ShadowSocks, Wireguard, Hysteria, Tunnel, Mixed, HTTP, Tun, MTProto). The repository metadata lists Go as its primary language. The metadata lists the GPL-3.0 license. This article stays within the project description and details documented in the GitHub repository README.
At a glance
- What is it?
- 3X-UI is an open-source web panel for managing Xray-core servers, supporting a wide range of protocols, per-client traffic and IP limits, and multi-node setups. This review covers its installation, database options, and the operational trade-offs you should weigh before adopting it.
- Who is it for?
- Adopt 3X-UI if you run a personal or small-scale Xray server and need a web UI to manage multiple protocols, per-client traffic and IP limits, and subscriptions without writing config files from scratch. Avoid it for production or commercial use, as the README explicitly states it is intended for personal use only.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- MHSanaei/3x-ui49,904 ★ · +5,342
| Repository | 2026-08-13 | 2026-11-14 |
|---|---|---|
| MHSanaei/3x-ui | 44.6k | 49.9k |
5,342 Stars in the last 93 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What 3X-UI Solves and Who It Is For
3X-UI addresses the pain of managing Xray-core servers through raw JSON config files. For an operator juggling multiple protocols, dozens of clients, and different traffic limits, editing Xray's configuration by hand is error-prone and time-consuming. This panel provides a web interface to create inbounds, add clients, set expiry dates, and monitor traffic. It is a fork of the original X-UI project, so it inherits the familiar workflow but adds broader protocol support and per-client accounting. The README is blunt about the target audience: 'This project is intended for personal use only. Please do not use it for illegal purposes or in a production environment.' That sentence should guide your evaluation. If you are a hobbyist running a VPS for yourself and a few friends, 3X-UI fits. If you are building a commercial proxy service, look elsewhere.
How It Works: Protocols, Transports, and the Panel Architecture
Under the hood, 3X-UI is a Go application that wraps Xray-core and exposes a web panel. It supports a long list of inbound protocols: VLESS, VMess, Trojan, Shadowsocks, WireGuard, Hysteria2, HTTP, SOCKS (Mixed), Dokodemo-door/Tunnel, and TUN. For transports, it covers TCP, mKCP, WebSocket, gRPC, HTTPUpgrade, and XHTTP, with TLS, XTLS, and REALITY security options. The panel lets you configure fallbacks, so you can serve multiple protocols on a single port, like VLESS and Trojan on 443, using Xray's fallback mechanism. Client management is the core feature: each client can have a traffic quota, an expiry date, an IP limit, and live online status. The panel also generates share links, QR codes, and subscription URLs, which are essential for distributing access to users. For multi-server setups, the panel supports managing multiple nodes from one instance. 3X-UI's breadth of protocol support is what sets it apart.
Getting It Running: Installer, Docker, and Environment Variables
The quick start is a one-line installer: `bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)`. You can append a version tag like `v3.7.0` to install a specific release, or `dev-latest` for a rolling pre-release from the main branch. The installer is non-interactive if you set `XUI_NONINTERACTIVE=1` or pipe with no TTY, which writes random credentials to `/etc/x-ui/install-result.env`. After installation, you run `x-ui` to open a management menu for starting/stopping the service, resetting credentials, and managing SSL certificates. For Docker, `docker compose up -d` uses SQLite by default. The environment variables are documented: `XUI_DB_TYPE` (sqlite or postgres), `XUI_DB_DSN` for the connection string, and `XUI_INIT_WEB_BASE_PATH` for the web panel's initial URI path. The installer writes these to `/etc/default/x-ui`.
Database Choice: SQLite vs. PostgreSQL and Migration
3X-UI supports two storage backends. SQLite is the default, storing everything in a single file at `/etc/x-ui/x-ui.db`. It requires zero setup and is fine for small to medium deployments. PostgreSQL is recommended for high client counts or multi-node setups. The installer can install PostgreSQL locally or accept an existing DSN. Migration from SQLite to PostgreSQL is a one-command operation: `x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"`, then you set the `XUI_DB_TYPE` and `XUI_DB_DSN` in `/etc/default/x-ui` and restart with `systemctl restart x-ui`. The README notes that the source SQLite file is left untouched, so you must remove it manually after verifying the new backend works. This is a clean approach, but it also means you have to remember to clean up. The choice of database affects performance and concurrency; if you plan to manage hundreds of clients, PostgreSQL is the safer bet.
Fail2ban Integration and Its Docker Caveat
A notable feature is Fail2ban integration to enforce per-client IP limits. The Docker image bundles Fail2ban, enabled by default, and it bans offenders with `iptables`. This requires the `NET_ADMIN` capability, which the provided `docker-compose.yml` grants via `cap_add`. If you start the container with `docker run` instead, you must add `--cap-add=NET_ADMIN --cap-add=NET_RAW` yourself. The comments in docker-compose.yml are explicit: without these capabilities, bans are logged but never applied. This is a real operational gotcha. If you deploy outside Docker, you need to ensure Fail2ban is installed and configured correctly on the host. The panel's IP limit feature is only as good as the underlying ban mechanism. For a personal server, this is manageable, but it adds complexity that you might not expect from a 'web panel'.
Limitations and When It Is the Wrong Tool
The most obvious limitation is the README's own warning: not for production use. That means no SLA, no guarantees, and the project may have bugs that affect availability. The panel supports a vast array of protocols, but with that breadth comes complexity. If you only need a single protocol like VLESS with WebSocket, a simpler tool like the original X-UI or even manual Xray config might be less overhead. Also, the project's rolling `dev-latest` build is available, but it is a pre-release and likely unstable; you should stick to tagged releases. Another limitation is that the README is only a summary; the full documentation, including configuration and the API reference, is at docs.sanaei.dev. The features list names routing rules, outbound chaining and multi-node management, so expect a learning curve for those.
Alternative: X-UI and Manual Xray Configuration
The direct alternative is the original X-UI project, from which 3X-UI is forked. X-UI offers a similar web panel for Xray, but with fewer protocols and features. If you need only basic VMess or VLESS support, X-UI might be simpler and more stable. Another approach is to skip a panel entirely and manage Xray-core directly with JSON config files. This gives you full control and avoids any panel-specific quirks, but you lose the web UI, per-client traffic accounting, and subscription generation. For a single user or a small group, manual config is viable if you are comfortable with Xray's syntax. For larger setups, 3X-UI's per-client limits and subscription server are compelling. The choice comes down to how much you value the GUI versus the control and simplicity of raw config.
Maintenance, Upgrade Cost, and License
The project is under active development, with recent releases like v3.11.0 (2026-10-25) and v3.10.2 (2026-10-14). The last push was 2026-11-02, so it is not abandoned. You can re-run the installer with a version tag to install a specific release. The `dev-latest` build is a per-commit pre-release, so using it means frequent changes and potential breakage; stick to stable tags for production (though production is discouraged). The license is GPL-3.0, which means if you modify and distribute the software, you must make your source code available under the same license. For personal use, this has no practical impact, but for a commercial offering, it is a significant constraint. Before deploying, check docs.sanaei.dev for upgrade instructions and backup procedures.
Editorial conclusion
Adopt 3X-UI if you run a personal or small-scale Xray server and need a web UI to manage multiple protocols, per-client traffic and IP limits, and subscriptions without writing config files from scratch. Avoid it for production or commercial use, as the README explicitly states it is intended for personal use only. Before deploying, verify your chosen distribution is supported, decide between SQLite and PostgreSQL based on client count, and confirm that Fail2ban's NET_ADMIN capability is available in your Docker or VPS environment, otherwise IP limits will not be enforced. Also, review the GPL-3.0 license implications if you plan to modify or redistribute the panel.
Frequently asked questions
What is 3X-UI used for?
It is a web control panel for managing Xray-core servers, covering inbound protocols including VLESS, VMess, Trojan, Shadowsocks, WireGuard, AmneziaWG, TUIC v5, Hysteria2, MTProto, HTTP, SOCKS, Dokodemo-door and TUN. On top of that it adds per-client traffic quotas, expiry dates, IP limits, a subscription server and multi-node management.
How do I install 3X-UI?
Run the installer from the quick start, which generates a random username, password and access path during installation, then use the x-ui command for the management menu. Passing dev-latest instead of a tag installs the rolling per-commit pre-release from main, and setting XUI_NONINTERACTIVE=1 runs it with no prompts and writes the credentials to /etc/x-ui/install-result.env.
Where can I find the 3X-UI configuration file?
There is no single config file. The panel reads XUI_* environment variables, and on a script install the installer writes them to the distribution's service environment file: /etc/default/x-ui, /etc/conf.d/x-ui or /etc/sysconfig/x-ui. Under Docker the same variables go into docker-compose.yml or a docker run -e list, and on a script install a change needs systemctl restart x-ui.
Is 3xui free to use?
The project is licensed GPL-3.0 and is an enhanced fork of the original X-UI project. It also states that it is intended for personal use only and should not be used in a production environment, so the licence does not come with any support commitment for a service you depend on.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/mhsanaei-3x-ui)Star history chart for your README
[](https://hysenlabs.com/projects/mhsanaei-3x-ui)Was this useful?