3X-UI: Open-source Web Control Panel for Xray-core

3X-UI: A Deep Dive into the Open-Source Web Control Panel for Xray-core

Introduction

In the evolving world of proxy and VPN management, 3X-UI stands out as a robust, open-source web control panel designed to simplify deployment, configuration, and monitoring of Xray-core servers. Built as an enhanced fork of the original X-UI project, 3X-UI broadens protocol support, improves stability, and adds thoughtful features that cater to both individuals running a single VPS and administrators overseeing multi-node deployments. It offers a clean, multilingual interface that unifies inbounds, clients, outbound routes, subscriptions, and analytics under one intuitive dashboard. While the project invites exploration and experimentation, it also carries an important caveat: this project is intended for personal use only. Please do not use it for illegal purposes or in a production environment without due consideration and proper safeguards.

A Quick Look at What 3X-UI Delivers

3X-UI is more than a pretty control panel. It is a practical toolkit for operators who want to streamline their Xray-core ecosystems. The interface provides a cohesive workflow for deploying a variety of protocols, managing users, and observing traffic patterns, all from a single pane of glass. The design embraces modern transports, security, and scalability, while also recognizing the realities of real-world deployments—like multi-node architectures, traffic quotas, and the need for reliable routing and monitoring.

• Multi-protocol inbounds
• Modern transports and security
• Fallbacks to run multiple protocols on a single port
• Per-client management with quotas, expiry dates, IP limits, and one-click sharing
• Comprehensive traffic statistics
• Multi-node support for scalable deployments
• Flexible outbound routing and chaining
• Built-in subscription server with multiple output formats
• Telegram bot for remote management
• RESTful API with in-panel Swagger documentation
• Flexible storage choices: SQLite by default or PostgreSQL
• 13 UI languages with both dark and light themes
• Fail2ban integration to enforce per-client IP limits

A Note on Design Philosophy

3X-UI embraces a philosophy of clarity and practical utility. The interface aims to reduce the friction of operating complex proxy setups while preserving the flexibility needed by power users. It is designed to work from a single VPS, but scales gracefully to multi-node deployments, enabling operators to manage diverse environments from a centralized control plane. The project’s open-source nature invites feedback, contributions, and community-developed enhancements, which helps keep the ecosystem vibrant and adaptable to changing security and performance needs.

Visual Identity: Logo and Screenshots

The project provides a clean visual identity to accompany its capabilities. At the top of project pages, you’ll see a logo image that captures the modern, technical vibe of 3X-UI:

• 3X-UI logo: an emblem of the project’s branding

Additionally, multiple screenshots illustrate the workflow and user experience of the panel, offering a glimpse into how inbounds, clients, and nodes are configured within the UI. The following visuals give a concrete sense of how the interface looks in practice:

• Overview screenshot
• Inbounds configuration screenshot
• Add client workflow screenshot
• Nodes/configs screenshot

Screenshots:

• Overview: [Image: 01-overview-light.png]
• Inbounds: [Image: 02-add-inbound-light.png]
• Add client: [Image: 03-add-client-light.png]
• Nodes/configs: [Image: 05-add-nodes-light.png]

Note: The images above are embedded to reflect the real-world layout and controls a user would encounter when working with 3X-UI.

What You Can Do with 3X-UI

1) Proactive, Flexible Protocol Support

3X-UI is built to handle a wide range of protocols through inbounds and transports. It offers a curated set of options to deploy and monitor VLESS, VMess, Trojan, Shadowsocks, WireGuard, Hysteria2, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel, and TUN. This breadth makes it possible to craft complex topologies that suit specific performance or policy requirements, all from a single pane.

• Inbound versatility: choose from multiple protocols and transport modes
• Transport diversity: TCP Raw, mKCP, WebSocket, gRPC, HTTPUpgrade, XHTTP
• Security layering: TLS, XTLS, and REALITY for reinforced privacy and integrity
• Fallback support: run multiple protocols on one port (e.g., VLESS and Trojan on 443) using Xray’s built-in fallback features

2) Operational Clarity with Per-Client Management

Managing per-client settings is a core strength of 3X-UI. The panel allows administrators to define and enforce quotas, expiry dates, IP limits, and live online status for each user. The ability to generate and share one-click links, QR codes, and subscriptions streamlines onboarding and distribution while keeping control centralized.

• Traffic quotas and expiry control per client
• Real-time online status indicators
• One-click shareable configurations and QR codes
• Subscriptions in multiple output formats

3) Insight through Traffic Statistics

Observability is central to maintaining service quality. 3X-UI provides traffic statistics per inbound, per client, and per outbound, with configurable reset controls. This empowers operators to identify trends, detect anomalies, and enforce policies effectively.

• Granular statistics across inbound, client, and outbound flows
• Reset controls to manage retention and privacy needs

4) Multi-Node and Outbound Routing

As deployments scale, the need to coordinate multiple servers becomes essential. 3X-UI includes multi-node support, enabling central management of several servers. It also supports outbound routing strategies, including WARP, NordVPN, custom rules, load balancing, and outbound proxy chaining—giving operators the flexibility to shape traffic at scale.

• Centralized management across multiple servers
• Diverse outbound routing options and chaining

5) Built-In Subscriptions and Automation

A built-in subscription server supports multiple output formats and templates. This feature is particularly useful for distributing client configurations to end users or downstream systems. The project also includes a RESTful API with in-panel Swagger documentation, enabling automation and integration with external tooling.

• Multi-format subscriptions
• Customizable page templates
• RESTful API withSwagger docs for automation

6) Security and Access Control

Security is woven into 3X-UI’s design through TLS-based transports, Fail2ban integration, and a range of hardening options. Fail2ban enforces per-client IP limits by integrating with IPTables, helping to deter abusive usage and protect resources.

• TLS/XTLS/REALITY secure transports
• Fail2ban-based IP-limit enforcement

7) Flexible Storage and Database Options

3X-UI supports two backends chosen during installation. SQLite provides a simple, zero-setup default suitable for smaller deployments. PostgreSQL is recommended when you expect higher client counts or multi-node setups. The installer can provision PostgreSQL locally or connect to an existing server using a DSN.

• Default SQLite database at /etc/x-ui/x-ui.db
• PostgreSQL for scalable deployments
• Environment-driven backend selection (e.g., XUIDBTYPE, XUIDBDSN)

8) Multilingual, Themed UI

With support for 13 languages and two themes (dark and light), 3X-UI makes it accessible to a broad audience. Language coverage includes English, فارسی, العربية, 中文（简体）, 中文（繁體）, Español, Русский, Українська, Türkçe, Tiếng Việt, 日本語, Bahasa Indonesia, and Português (Brasil).

• 13 languages for the panel interface
• Dark and light themes to suit preferences and lighting

Getting Started: Quick Start and Beyond

A straightforward way to begin is to run the installer script, which fetches the latest components and configures the initial setup. The process generates a random username, password, and access path for secure first-time access. After installation, you can use the management menu to start/stop the service, view or reset credentials, manage SSL certificates, and more.

• Quick start command:
• bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
• To install a specific version:
• bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
• To install the rolling development build (latest per-commit pre-release from main):
• bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest

Unattended Install (Cloud-Init)

For cloud environments, 3X-UI can perform non-interactive installations. Set XUI_NONINTERACTIVE=1 or pipe commands with no TTY. The installer will complete end-to-end, generating random credentials and writing them to /etc/x-ui/install-result.env. This is particularly useful for automated deployments across cloud platforms.

• Cloud-init-ready deployment notes are available under deploy/cloud-init/
• Hetzner cloud notes provide cloud-init deployment specifics

Supported Platforms and Architectures

Operating Systems

• Ubuntu, Debian, Armbian, Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux, Virtuozzo, Arch, Manjaro, Parch, openSUSE (Tumbleweed / Leap), Alpine, and Windows

Architectures

• amd64, 386, arm64 (aarch64), armv7, armv6, armv5, s390x

Database Options: SQLite vs PostgreSQL

SQLite (default)

• A single file at /etc/x-ui/x-ui.db
• Zero setup, ideal for small-to-medium deployments
• Light footprint and straightforward maintenance

PostgreSQL

• Recommended for higher client counts or multi-node setups
• The installer can install PostgreSQL locally or you can point to an existing server with a DSN
• Runtime backend selection is controlled via environment variables:
• XUIDBTYPE=postgres
• XUIDBDSN=postgres://xui:[email protected]:5432/xui?sslmode=disable

Migration Path: SQLite to PostgreSQL

If you begin with SQLite but later decide to migrate to PostgreSQL, the migration workflow is designed to be safe and straightforward:

• Command to migrate:
• x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
• After migration, update /etc/default/x-ui with XUIDBTYPE and XUIDBDSN and restart:
• systemctl restart x-ui
• The source SQLite file remains untouched; delete it manually after you confirm a successful migration

Docker Considerations

The default Docker setup continues to use SQLite, but there is a profile for PostgreSQL. To spin up PostgreSQL-backed deployment, you can modify docker-compose.yml and use the following profile:

• docker compose --profile postgres up -d

Note: Fail2ban is included in the image and is enabled by default to enforce per-client IP limits. When running in Docker, the container requires NET_ADMIN and related capabilities to enforce bans via IPTables. If you use docker run, you must add capabilities:

• --cap-add=NETADMIN --cap-add=NETRAW

Environment Variables: What You Can Tune

The environment variables give you granular control over behavior and backend selection. A representative subset includes:

• XUIDBTYPE: Database backend, sqlite or postgres (default sqlite)
• XUIDBDSN: PostgreSQL connection string when XUIDBTYPE=postgres
• XUIDBFOLDER: Directory for the SQLite database file (default /etc/x-ui)
• XUIDBMAXOPENCONNS: Maximum open connections for PostgreSQL pool
• XUIDBMAXIDLECONNS: Maximum idle connections for PostgreSQL pool
• XUIINITWEBBASEPATH: Initial URI path for the web panel (default /)
• XUIENABLEFAIL2BAN: Enable Fail2ban-based IP-limit enforcement (default true)
• XUILOGLEVEL: Logging verbosity (debug, info, warning, error)
• XUI_DEBUG: Enable debug mode (default false)
• XUITUNNELHEALTH_MONITOR: Enable tunnel health monitoring (default false)
• XUITUNNELHEALTH_PROXY: Proxy the health probe is sent through (e.g., socks5://127.0.0.1:1080)
• XUITUNNELHEALTH_URL: URL probed for tunnel health
• XUITUNNELHEALTH_INTERVAL: Interval between probes
• XUITUNNELHEALTH_TIMEOUT: Per-probe timeout
• XUITUNNELHEALTH_FAILURES: Consecutive failures before a restart
• XUITUNNELHEALTH_COOLDOWN: Minimum delay between restarts

Supported Languages

The panel UI ships with 13 languages to accommodate diverse users:

• English
• فارسی
• العربية
• 中文（简体）
• 中文（繁體）
• Español
• Русский
• Українська
• Türkçe
• Tiếng Việt
• 日本語
• Bahasa Indonesia
• Português (Brasil)

Contributing and Community

Contributions are welcome. If you’re interested in contributing, please read the Contributing Guide before opening issues or pull requests. Your input helps to refine features, fix issues, and broaden compatibility across environments.

A Special Thanks and Acknowledgments

The project acknowledges individual contributors and community resources that helped shape 3X-UI:

• Acknowledgments to Iran v2ray rules and Russia v2ray rules repositories for routing rule sets that enhance security and domain-level controls
• Community tools such as the terraform-provider-3x-ui for managing inbounds, clients, panel settings, and Xray configuration as code

Support and Donations

If the project proves useful, there are ways you can show appreciation and support ongoing development:

• Buy Me A Coffee link (an image button is provided in project assets)
• Crypto donation button (NOWPayments) as an alternative donation channel

Using 3X-UI: Practical Scenarios

• A single VPS hosting a multi-protocol Xray-core instance with VLESS, VMess, and Trojan on common ports, backed by TLS and REALITY
• A multi-node deployment across several servers, with centralized management, consistent policy enforcement, and unified traffic analytics
• An automated onboarding process that distributes per-client configurations via subscriptions and QR codes
• A monitoring loop via the Telegram bot that surfaces key metrics and allows remote control actions

Important Considerations for Real-World Use

• Security posture: While 3X-UI provides strong controls, always implement best practices for credential management, TLS configuration, and firewall rules. Fail2ban is a powerful tool, but it must be configured thoughtfully to avoid unnecessary lockouts.
• Legal and ethical use: The project’s warning emphasizes personal use and compliance with local laws. Ensure your deployments respect regulations and do not facilitate illicit activities.
• Backups and disaster recovery: With multi-node deployments and per-client data, regular backups of the database are essential. Consider a disaster recovery plan that includes consistent snapshotting and tested restore procedures.
• Performance considerations: Depending on traffic levels and the number of clients, PostgreSQL may provide performance and reliability gains over SQLite. Plan capacity accordingly and monitor database metrics.

A Final Word

3X-UI represents a practical, feature-rich approach to managing Xray-core servers through a cohesive web interface. By combining an extensive protocol repertoire, per-client governance, rich telemetry, and multi-node management, it lowers the operational overhead of running modern proxy networks. The inclusion of a built-in subscription server, RESTful API, and community tooling further enhances its utility in both personal and semi-professional environments. The project’s commitment to multiple languages and accessible UI themes also makes it approachable for a global audience.

If you’re curious about the capabilities and want a tangible feel of the platform, start with the quick-start installer, explore the screenshots to understand the layout, and then dive into per-client configurations, inbound setups, and subscription distributions. As you grow your deployment, remember to leverage PostgreSQL for scalable, multi-node configurations, and consider the cloud-ready, unattended install paths for prolific, automated rollouts.

Images Included from the Input

• 3X-UI logo: the main visual anchor for the project (as shown in the header)
• Screenshots:
• Overview: ./media/01-overview-light.png
• Inbounds: ./media/02-add-inbound-light.png
• Add client: ./media/03-add-client-light.png
• Nodes/configs: ./media/05-add-nodes-light.png

These visuals provide a concrete sense of how the interface presents itself during typical workflows and help new users envision the UI’s layout and interaction patterns.

Closing Thoughts

3X-UI is more than a management console; it’s a capable, extensible platform designed to simplify the complexities of modern Xray-core deployments. With thoughtful features, flexible storage options, robust security hooks, and a friendly multilingual experience, it meets the needs of hobbyists and professionals who seek control, observability, and scalability in one integrated solution. If you’re looking to tame a diverse proxy ecosystem without sacrificing accessibility or power, 3X-UI is a compelling option worth exploring.