3X-UI is an advanced, open-source web control panel for managing Xray-core servers. It provides a clean, multi-language interface for deploying, configuring, and monitoring a wide range of proxy and VPN protocols — from a single VPS to multi-node deployments.
Built as an enhanced fork of the original X-UI project, 3X-UI adds broader protocol support, improved stability, per-client traffic accounting, and many quality-of-life features.
[!IMPORTANT]
This project is intended for personal use only. Please do not use it for illegal purposes or in a production environment.
Modern transports & security — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade, and XHTTP, secured with TLS, XTLS, and REALITY.
AmneziaWG built in — DPI-resistant WireGuard runs inside the panel on a userspace network stack, with no kernel module, DKMS, or extra packages to install.
MTProto proxies — per-client FakeTLS secrets, ad-tags, and quotas, applied live without dropping existing connections.
Fallbacks — serve multiple protocols on a single port (e.g. VLESS and Trojan on 443) using Xray's fallback support.
Per-client management — traffic quotas, expiry dates, IP limits with trusted-address exemptions, HWID device limits, scheduled renewal cycles, live online status, and one-click share links, QR codes, and subscriptions.
Traffic statistics — per inbound, per client, and per outbound, with reset controls.
Multi-node support — manage and scale across multiple servers from a single panel, including cloning inbounds onto other nodes.
Outbound & routing — WARP, NordVPN, PIA, custom routing rules, load balancers with balancer-to-balancer fallback, and outbound proxy chaining. Bundled geosite and geoip categories are browsable straight from the rule editor.
Built-in subscription server — raw, JSON, and Clash output, auto-selected from the client's User-Agent, plus custom page templates.
Telegram bot for remote monitoring and management.
RESTful API with scoped, optionally expiring tokens and an in-panel API reference.
Installable panel (PWA) — pin 3X-UI to a desktop or phone home screen.
Flexible storage — SQLite (default) or PostgreSQL.
13 UI languages with dark and light themes.
Fail2ban integration for enforcing per-client IP limits.
During installation a random username, password, and access path are generated. After installation, run x-ui to open the management menu, where you can start/stop the service, view or reset your login credentials, manage SSL certificates, and more.
Every release asset is published with a .sha256 sum next to it. Both install.sh and the updater verify the archive against that sum and abort on a mismatch.
For full documentation — installation, configuration, operations, and the complete API reference — visit docs.sanaei.dev.
Unattended install
The installer also runs non-interactively for cloud-init.
Set XUI_NONINTERACTIVE=1 (or pipe with no TTY) and it installs end-to-end with
zero prompts, generating random credentials and writing them to
/etc/x-ui/install-result.env. See deploy/ for:
Cloud-init user-data — unattended install on any cloud (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle)
3X-UI supports two backends, chosen during the install:
SQLite (default) — a single file at /etc/x-ui/x-ui.db. Zero setup, ideal for small and medium deployments.
PostgreSQL — recommended for high client counts or multi-node setups. The installer can install PostgreSQL locally for you, or accept a DSN to an existing server.
At runtime the backend is selected via environment variables (the installer writes these to /etc/default/x-ui for you):
Migrating an existing SQLite install to PostgreSQL
x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
# then set XUI_DB_TYPE and XUI_DB_DSN in /etc/default/x-ui and restart:
systemctl restart x-ui
The source SQLite file is left untouched; remove it manually once you have verified the new backend.
Docker
The default docker compose up -d keeps using SQLite. To run with the bundled PostgreSQL service, uncomment the two XUI_DB_* env lines in docker-compose.yml and start with the profile:
docker compose --profile postgres up -d
The image bundles Fail2ban (enabled by default) to enforce per-client IP limits. Fail2ban bans offenders with iptables, which requires the NET_ADMIN capability. docker-compose.yml already grants it via cap_add; if you start the container with docker run instead, add the capabilities yourself, otherwise bans are logged but never applied:
docker run -d --cap-add=NET_ADMIN --cap-add=NET_RAW ... ghcr.io/mhsanaei/3x-ui
Enable the tunnel health monitor (probes a URL and restarts xray after repeated failures; a restart drops all clients)
false
XUI_TUNNEL_HEALTH_PROXY
Proxy the probe is sent through; point it at a local xray inbound so the probe tests the tunnel (e.g. socks5://127.0.0.1:1080). Empty means the probe only checks host connectivity
—
XUI_TUNNEL_HEALTH_URL
URL probed for tunnel health
https://www.cloudflare.com/cdn-cgi/trace
XUI_TUNNEL_HEALTH_INTERVAL
Interval between probes
30s
XUI_TUNNEL_HEALTH_TIMEOUT
Per-probe timeout
10s
XUI_TUNNEL_HEALTH_FAILURES
Consecutive failures before a restart is triggered
3
XUI_TUNNEL_HEALTH_COOLDOWN
Minimum delay between consecutive restarts
5m
NODE_TOKEN_ENCRYPTION
Encryption at rest for node API tokens: off, migration, or required (note: no XUI_ prefix)
off
XUI_NODE_TOKEN_KEY_FILE
JSON keyring (mode 0600) holding the active key id and its base64 32-byte keys
/etc/x-ui/node_token_key.json
XUI_NODE_TOKEN_KEY
A single base64 32-byte key, used only when the key file cannot be loaded
Iran v2ray rules (License: GPL-3.0): Enhanced v2ray/xray and v2ray/xray-clients routing rules with built-in Iranian domains and a focus on security and adblocking.
Russia v2ray rules (License: GPL-3.0): This repository contains automatically updated V2Ray routing rules based on data on blocked domains and addresses in Russia.
Community Tools
Tools and integrations built by the community around 3x-ui.
terraform-provider-3x-ui (License: MIT): Manage inbounds, clients, panel settings, and Xray configuration as code with Terraform / OpenTofu.
Support project
If this project is helpful to you, you may wish to give it a:star2:
What is this?3X-UI is an open-source web control panel for managing Xray-core servers, letting you deploy, configure, and monitor many proxy and VPN protocols from one VPS or across multiple nodes.
Is this a desktop app, or something I access through a browser?It is a self-hosted web panel you reach through a browser after installing it on a Linux (or Windows) server; the install also drops an 'x-ui' command-line menu on the box for starting/stopping the service and managing credentials.
How do I install it on my VPS?Run the install script from the Quick Start section (optionally pinned to a version tag, or dev-latest for the rolling build); it generates a random username, password, and access path for you automatically.
Which operating systems and architectures are supported?It runs on most mainstream Linux distros (Ubuntu, Debian, Fedora, CentOS, Arch, Alpine, and more) plus Windows, across amd64, 386, arm64, armv7/6/5, and s390x.
Is this safe to run in a production environment?The project explicitly says it is meant for personal use only and warns against production or illegal use, so treat it as a hobbyist/self-hosting tool rather than an enterprise-ready product.
What is AmneziaWG and why is it included?AmneziaWG is a DPI-resistant variant of WireGuard that runs entirely inside the panel on a userspace network stack, so you get censorship-resistant WireGuard without installing any kernel module or extra packages.
Is there a way to manage the panel without logging into the web UI?Yes, there is a built-in Telegram bot for remote monitoring and management of the panel.
Which database should I use, SQLite or PostgreSQL?SQLite is the default and needs zero setup, fine for small or medium deployments; PostgreSQL is recommended for high client counts or multi-node setups, and the installer can set it up for you.
3X-UI is an open-source web control panel for managing Xray-core servers, letting you deploy, configure, and monitor many proxy and VPN protocols from one VPS or across multiple nodes.