🇷🇺 Русский · 🇬🇧 English · 🇪🇬 العربية · 🇮🇷 فارسی · 🇨🇳 简体中文 · 🇪🇸 Español · 🇹🇷 Türkçe
REALITY · XHTTP · HYSTERIA2 · NGINX · HTTPS · BACKUP / RESTORE
Two domains, a clean VPS, and a few minutes to install.
📦 Releases · 🔗 Cascade · 🌐 Cover websites ·
3X-UI AUTO NGINX is a free installer for deploying 3x-ui and Xray on your own VPS. It configures Nginx, HTTPS certificates, REALITY, XHTTP, Hysteria2, subscriptions (including in Clash/Mihomo format), and diagnostics. Its interactive manager handles server installation, domain changes, Backup/Restore v3, and a two-VPS Cascade. Optional features include XTLS Vision, AmneziaWG 3.1, Cloudflare WARP for Russian websites, and AdGuard Home with DNS-over-HTTPS (DoH).
More than a standard 3x-ui installation: new servers get their own multi-page websites for the panel and REALITY. There are at least 2,592 ready-made combinations of design and text, with further variations in colors, icons, and dates on each installation. The sites have working navigation and additional pages. On the REALITY domain, ordinary HTTPS requests over TCP and unauthenticated HTTP/3 requests over UDP serve the same website. The existing Nginx and Xray components handle everything, with no Docker or additional web servers.
| Ready-to-use connections REALITY, XHTTP, and Hysteria2 are configured automatically. Optional XTLS Vision, AmneziaWG, and CDN-ready XHTTP connections are also set up automatically when selected. |
Complete cover websites At least 2,592 ready-made combinations of design and text. Multi-page sites with working navigation, their own copy and images, plus Hysteria2 HTTP/3 cover. |
| Two-VPS Cascade Connect two servers through the manager menu. Russian sites and IP addresses use the entry server directly; other traffic goes through the exit server. |
Your own Nginx and HTTPS Nginx on your VPS handles incoming TCP connections. The panel and subscriptions use HTTPS on your own domain, without exposing internal ports directly to the internet. |
| Backup / Restore v3 Backup, recovery, and migration to another VPS while preserving user data and personalized sites. |
Manager and domain changes Change the panel domain, REALITY domain, or both without reinstalling 3X-UI or other services. |
| Automatic certificates and security Let's Encrypt certificates renew automatically without stopping Nginx; optional SSH protection and automatic VPS security updates. |
Additional features XTLS Vision, AmneziaWG 3.1, CDN-ready XHTTP, Cloudflare WARP, AdGuard Home with DoH, and Cascade setup. |
Point the DNS records of two domains to your VPS IP address: one for the panel and one for REALITY. Connect via SSH as root and make sure inbound TCP ports 80 and 443 and UDP port 443 are reachable from the internet. Supported systems.
curl -fSL https://github.com/xPROMSx/3x-ui-auto-nginx/releases/latest/download/x-ui-latest.sh -o x-ui-latest.sh && bash x-ui-latest.shAfter launching, choose 1 — English or 2 — Русский. Then the main menu opens:
- 1 — Installation: set up a new server or perform a full reinstall.
- 2 — Change Domains: change the panel domain, REALITY domain, or both without reinstalling.
- 3 — Backups: create, list, and restore backups.
- 4 — Telegram Web Proxy Manager: launch or install the separate Telegram proxy manager.
- 5 — Cascade: connect two servers, check status, or disconnect.
- 0 — Exit.
The menu requires an interactive SSH terminal.
Fallback download — if GitHub Releases is unavailable
The main branch contains an alpha version of the project. Installing it is not recommended. Use the stable release from the main command above.
curl -fSL https://raw.githubusercontent.com/xPROMSx/3x-ui-auto-nginx/main/x-ui-latest.sh -o x-ui-latest.sh && bash x-ui-latest.shCaution
Installation is not an update!
Running the script again without arguments opens the manager; it does not reinstall the server. However, Installation is intended for a clean VPS or a full reinstall.
If an existing installation is detected, the script warns that managed data will be removed and requires the exact confirmation YES. Reinstalling replaces the 3X-UI database and nginx configuration. Save a backup outside the VPS first.
Change Domains and Backups are separate operations that do not reinstall the panel.
How do I update?
- 3X-UI and Xray: use the panel's built-in update tools. New versions may not yet be verified with this project's configuration.
- 3X-UI AUTO NGINX: updating the installed stack in place is not supported. To use new manager features such as 5 — Cascade, download the current script and select that operation. The manager checks whether your installed configuration is compatible.
- Backup / Restore: saves and restores data; it does not update the stack.
Do not select Installation just to update! Update nginx, the Linux kernel and other system packages using your operating system's tools.
The settings below are offered when you select Installation from the main menu.
Enter the domain for your 3X-UI panel:
Enter the domain used for the administration panel, subscriptions, and additional web services.
Enter the domain for VLESS REALITY:
Enter a second domain for REALITY. Both domains must point to your VPS IP address.
ℹ️ Additional startup parameters
You can supply both domains on the command line instead of entering them interactively:
bash x-ui-latest.sh -subdomain panel.example.com -reality_domain reality.example.comReplace panel.example.com and reality.example.com with your own domains. Optional features are still selected interactively.
Enhance VPS security? [Y/n]:
Recommended for less experienced users · Enabled by default (Y)
The installer configures Fail2ban for SSH protection, encrypted system DNS (DoT), and automatic security updates. When conditions permit, it also creates a 1 GiB swap file, regardless of whether enhanced security is selected.
Read the settings below before enabling this option, particularly the automatic reboot schedule.
🔐 Detailed security settings
Choosing Y enables the additional security settings. Swap setup runs independently of this choice:
- 1 GiB swap. If no swap is active, the filesystem is supported and at least 4 GiB is free, the installer creates and enables a swap file. Existing swap settings remain unchanged. If these conditions are not met, this step is skipped without stopping installation.
- SSH protection — Fail2ban. Limits repeated unsuccessful logins using the actual SSH ports. Existing SSH authentication settings are not changed.
- Encrypted DNS (DoT). Global Cloudflare and Google resolvers use strict DNS-over-TLS through
systemd-resolved. Interface/VPN DNS routes and search domains are preserved; their queries may remain unencrypted. If DoT preparation fails and the original DNS is successfully restored, core, Fail2ban and automatic update installation continues independently of DoT; the final result reports the failure and exits nonzero. - Automatic security updates. Package lists are updated at 02:30, with security updates installed at 02:50.
- Automatic reboot — 04:38. If updates require a reboot, it occurs at the scheduled time, even when users are connected. This may interrupt active connections.
Times are in the VPS's local time zone.
Existing settings are checked for compatibility before changes. If security configuration fails, a controlled rollback is provided.
Important: This does not disable SSH password login or replace proper server administration. Configure SSH key access first, then disable password authentication yourself.
Set up an additional VLESS TCP/TLS (XTLS Vision) connection? (requires a separate domain) [y/N]:
Additional connection · Disabled by default (N)
An alternative VLESS connection over TLS that may help when REALITY is unstable or blocked on your network. It is created as a separate profile in 3X-UI.
Important
XTLS Vision requires a third domain, distinct from the panel and REALITY domains. Its DNS record must point to your VPS IP. HTTPS certificates and nginx routing are configured automatically.
After you choose Y, the installer asks for this domain: Enter the domain for VLESS TLS Vision (must differ from the panel and REALITY domains):.
Set up an additional AmneziaWG connection? [y/N]:
Additional connection · Disabled by default (N)
A separate AmneziaWG connection is created in the 3X-UI panel. No additional domain is required.
ℹ️ About Amnezia WG
The installer configures AmneziaWG 3.1 on UDP/8443 and automatically allows the required UFW rule.
After installation, create a client in the 3X-UI panel to obtain a configuration or a vpn:// link for a compatible Amnezia app.
The installer creates the server connection but does not automatically generate AmneziaWG clients.
The configuration and necessary firewall rule are included in Backup / Restore v3.
Add an additional CDN-compatible XHTTP connection? [y/N]:
Additional connection · Not installed by default (N)
Creates a separate VLESS connection using XHTTP in packet-up mode, preconfigured for use through a CDN. The connection is created disabled in 3X-UI.
It uses the panel’s existing HTTPS domain, so no additional domain or certificate is needed. Once enabled, it also works directly without a CDN.
To use a CDN, configure your provider yourself and adjust the Host settings in 3X-UI. The installer does not configure CDN services; it provides a server profile you can adapt to your setup.
Route Russian websites through Cloudflare WARP to hide your VPS IP? [y/N]:
Optional routing · Enabled by default in the Russian menu (Y), disabled in the English menu (N)
If this VPS will be a Cascade entry server, choose N. WARP is incompatible with the entry role, but it can be used on the exit server.
Selecting Y configures Cloudflare WARP (MASQUE) so Russian websites and certain network services see a Cloudflare IP address instead of your VPS IP address. This is needed to protect your VPS IP address.
The setting only affects traffic routed through your VPS. If an app accesses a website directly, WARP on the server has no effect.
When enabled, the installer registers a device with Cloudflare and accepts its terms of service.
If WARP setup fails, installation continues without it, and the final report indicates a partial result. If the rollback cannot be verified, check Xray in the panel.
ℹ️ Which sites use WARP and how to check the setup
The installer adds an outbound named warp-masque and three routing rules to the Xray configuration:
- WARP - RU: Russian domains from
geosite:category-ru. - WARP - RU2: IP addresses from
geoip:ru. - WARP - RU3:
ipify.org,ifconfig.me,checkip.amazonaws.com,ipapi.is,iplocate.io,ip.sb, and2gis.com.
The rules are appended to the routing list. Earlier rules keep their priority. This is not a separate client connection profile or a system-wide VPN: routing happens inside Xray.
After installation, check Xray → Outbounds for warp-masque and Xray → Routing for the three named rules in the 3X-UI panel. The settings are included in Backup v3 along with the 3X-UI configuration.
Install and configure AdGuard Home? [y/N]:
Optional DNS server · Disabled by default (N)
A personal DNS server for blocking ads and trackers, managing clients, and making encrypted DNS requests.
ℹ️ About AdGuard Home and access control
No additional domain is needed.
After installation, the following are available:
- AdGuard Home admin panel:
https://panel.example.com/adg-.../— a unique random path. - DNS-over-HTTPS:
https://panel.example.com/dns-query.
Public TCP/UDP port 53 is not opened. The AdGuard Home configuration and data are included in Backup / Restore v3.
For a personal VPS, create a separate ClientID for each device.
In AdGuard Home, go to Settings → DNS settings → Access settings → Allowed clients and enter only those ClientIDs, not IP addresses or subnets.
Use DoH URLs such as:
https://panel.example.com/dns-query/<ClientID>
Once configured, requests without an allowed ClientID, including requests to /dns-query, are rejected.
Choose long, random identifiers. See the official AdGuard Home security guidance.
Starting with v2.4.1, new installations let you check for and install AdGuard Home updates directly from its web interface. If you installed AdGuard Home with an earlier version of this installer, enable updates with one command on your VPS:
sudo bash -c 'set -euo pipefail; umask 077; d=$(mktemp -d); trap '\''rm -rf -- "$d"'\'' EXIT; cd "$d"; u=https://github.com/xPROMSx/3x-ui-auto-nginx/releases/download/v2.4.2; curl -fLsS --connect-timeout 15 --max-time 120 "$u/x-ui-latest.sh" -o x-ui-latest.sh; curl -fLsS --connect-timeout 15 --max-time 120 "$u/x-ui-latest.sh.sha256" -o x-ui-latest.sh.sha256; sha256sum --check --strict x-ui-latest.sh.sha256; bash ./x-ui-latest.sh --enable-agh-updates'
Create a client in 3X-UI and display a subscription link after installation? [Y/n]:
Recommended · Enabled by default (Y)
The installer creates a 3X-UI client and generates a personal HTTPS subscription URL for the configured, supported connections.
The link appears in the final installation report. If you decline, you can create clients manually through the panel.
The installation report displays the panel URL, username and password, diagnostics address, and subscription link (if you chose to create a client). For AdGuard Home, it also includes the admin address, password, and DoH endpoint. The report also shows the WARP setup result.
If an OS update requires a reboot, the installer will notify you. The initial reboot is manual: run sudo reboot.
Complete websites instead of basic placeholders. Fresh installations automatically create separate multi-page websites for the panel and REALITY. The project offers at least 2,592 ready-made design and text combinations, with working navigation, illustrations, and mobile-friendly layouts. Optional XTLS Vision gets its own website.
Every installation looks different. Site names, colors, images, icons, and text are personalized automatically. Additional pages have different articles and publication dates. The chosen site is preserved across Backup/Restore and domain changes.
Hysteria2 with HTTP/3 cover. Ordinary HTTPS requests over TCP and unauthenticated HTTP/3 requests over UDP on the REALITY domain receive the same complete website. The panel and subscriptions remain isolated from this public HTTP/3 cover.
| Connection | Status |
|---|---|
| VLESS + REALITY | ✅ Enabled by default |
| VLESS + XHTTP | ✅ Enabled by default |
| VLESS + XHTTP for CDN | 🔧 Optional, disabled |
| Hysteria2 | ✅ Enabled by default |
| VLESS + WebSocket (TLS) | ◻️ Disabled by default |
| Trojan + gRPC | ◻️ Disabled by default |
| VLESS + XTLS Vision | 🔧 Optional |
| Amnezia WG | 🔧 Optional |
REALITY, XHTTP, and Hysteria2 are enabled after installation. WebSocket TLS and Trojan gRPC are created but remain disabled until you enable them in the 3X-UI panel.
XTLS Vision, Amnezia WG, and XHTTP for CDN are added only if selected during installation. XHTTP for CDN is created disabled and will not appear in subscriptions until you enable it and attach a client.
Create clients automatically during installation or manually in the panel to use the connections. Amnezia WG clients are created separately.
Compatibility depends on the client app and its version. XHTTP through a CDN also depends on your provider’s settings and restrictions.
Standard subscriptions, JSON, and Mihomo / Clash are served via nginx and HTTPS. provider=1 returns the original subscription for proxy providers rather than a complete Clash configuration.
In the main menu, select 2 — Change Domains. You can change the panel domain, REALITY domain, or both without reinstalling. New DNS records must point to your VPS, and TCP/80 must be reachable for certificate issuance. The domains must differ from each other and from the Vision domain.
A full Backup v3 is created automatically before any changes. Clients, keys, settings and traffic statistics are preserved. The Vision domain remains unchanged. After a successful change, you may need to update subscription URLs and client configurations.
Only recognized project installations are supported, including compatible v2.1.7 installations. If an error occurs, do not delete backups or recovery data. If you see ROLLBACK_UNVERIFIED, stop and preserve the diagnostics. Details, limitations and recovery.
Open 3 — Backups in the main menu to create a backup, list archives or run Restore. You can use a backup after reinstalling the OS or to move to another VPS. To restore it, the operating system, its version and the CPU architecture must match the backup.
For command-line use, run the following as root:
# Create a new backup
x-ui-backup backup
# List available backups
x-ui-backup list
# Restore a selected backup
x-ui-backup restore /var/backups/x-ui/<archive>.tar.gzArchives are saved in /var/backups/x-ui/.
Backups contain sensitive data: the client database, passwords, and certificate private keys. Keep a copy off the VPS and restore only trusted archives.
If Restore is unavailable, extract the files for manual recovery without installing packages or running services. Only Bash, Python 3, and access to the archive and destination are needed; root is not required:
x-ui-backup extract /path/to/archive.tar.gz ./recovered-backupThe destination must be new; original paths are preserved under files/ and links are skipped. The data contains secrets: review it before copying anything over a running server.
Cascade connects two VPS servers running 3X-UI AUTO NGINX. Your devices connect to the entry server, while the exit server provides the internet connection. This may help if connecting to a particular VPS is unreliable or you need to access the internet through a server in another country.
Device → Entry VPS → Exit VPS → Internet
Russian sites and Russian IP addresses are reached directly from the entry server. You can turn off this behavior after setup in the entry VPS's routing rules. Other traffic not matched by earlier routing rules goes through the exit server.
Open 5 — Cascade in the main menu to set it up. You do not need to edit configuration files manually.
Set up Cascade, check its status, or disconnect
- Two VPS servers with working 3X-UI AUTO NGINX installations.
- The 3X-UI panel login and password for each server.
- The latest installer, with 5 — Cascade in the menu.
- No WARP configuration on the entry server (you can remove it manually).
On the VPS that you want to use for internet access, run the current installer.
Select 5 — Cascade → 1 — Create key (exit server).
Enter the 3X-UI panel login and password. Your input is hidden and neither credential is saved. The manager adds a special client named cascade to the existing REALITY connection and displays a key link starting with vless://.
Copy this link. You will need it on the second server.
Keep the key link private: anyone who has it can connect using this client.
Existing clients are not changed.
Now run the current installer on the VPS your devices connect to.
Select 5 — Cascade → 2 — Connect exit server (entry server).
Enter the 3X-UI panel login and password (again, neither is saved), then paste the key link from step 1. The link is visible in the terminal when pasted, but it is not saved.
The manager tests the connection to the exit server first. If the test succeeds, it adds an outbound connection called cascade-exit and three CASCADE routing rules.
Russian sites and IP addresses are routed directly from the entry server unless you later disable those rules. Other matching traffic uses the exit server.
Applying the changes may briefly interrupt every user's connection. If a check fails, the manager attempts to restore the previous configuration and reports the result.
Your existing client connections and subscriptions remain in use. No separate client profile is needed for Cascade.
On each VPS, open 5 — Cascade → 3 — Status.
The manager asks for the panel login and password, just as it does for other actions.
It shows whether the entry and exit roles are configured on that server and whether Xray is running. This check changes no settings.
On the relevant VPS, open 5 — Cascade → 4 — Disable.
On the entry server, the manager offers to remove cascade-exit and the three CASCADE rules. Other connections and panel rules remain in place.
On the exit server, only the cascade client is removed. Entry servers using its key will then lose access to that exit server.
Each removal requires separate confirmation. Applying changes on the entry server may briefly interrupt user connections.
- WARP: it cannot be configured on the entry server. If present, remove its outbound and routing rules in the 3X-UI panel before connecting. WARP is allowed on the exit server.
- AmneziaWG: these connections do not pass through the exit server.
- Routing rules: earlier user-defined rules may direct some traffic elsewhere. The manager warns you before connecting.
- Exit unavailable: traffic routed through the exit server stops working until the exit is reachable again. There is no automatic backup exit.
- QUIC over Vision: UDP/443 does not pass through this Cascade.
- Domain changes: after changing domains on the exit VPS, reconnect it from the entry server.
Backup v3 saves Cascade settings. Restoring a backup on the entry server retains the Cascade configuration alongside the other 3X-UI data.
Cascade has been tested on two real VPS servers using REALITY, XHTTP, and Hysteria2. Compatibility with every client app and configuration has not been confirmed.
If you find a bug, report it on GitHub.
Service interfaces are not exposed directly to the internet. The panel, subscriptions, and additional services are accessible through nginx and HTTPS, while internal ports remain local.
Not sure how to secure your VPS? Enable enhanced security during installation to configure protection against SSH brute-force attempts, encrypted DNS, and automatic security updates. Read the detailed settings and the scheduled nighttime reboot policy in Quick start first.
Important: Secure access to the server itself. Use SSH keys, verify key-based login works, and only then disable password authentication. The installer does not disable it automatically.
Telegram Web Proxy Manager is an independent companion project for running your own Telegram WEB Proxy, with HTTPS, a cover website, and updates with rollback.
TWPM is not part of the default 3X-UI installation. Main menu option 4 lets you launch it or start its separate installation after confirmation. Both projects are managed independently.
- Systems: Ubuntu 24.04, Ubuntu 26.04, and Debian 13.
- UFW: allows 80/tcp, 443/tcp and 443/udp (plus 8443/udp when AmneziaWG is selected). During Installation, inactive UFW is enabled only after SSH access has been checked; otherwise it remains off with a warning. The manager can enable UFW after Restore only if explicitly selected and the safety checks pass. Standalone
x-ui-backup restoredoes not enable UFW. - Certificates: Let's Encrypt webroot and
certbot.timerrenew certificates automatically without stopping nginx. - 3x-ui version: by default, the installer uses the latest version thoroughly tested for compatibility with 3X-UI AUTO NGINX, which may not be the latest upstream release. After installation, you can update 3x-ui using its built-in update mechanism, but the new version may not yet be verified against this configuration. You can also explicitly select another stable release with
-version <tag>(minimum supported version: v3.8.0); the installer will warn that compatibility has not been verified.
Match the backup's OS, OS version, and architecture. If the VPS IP address changes, update the DNS records for your domains. Do not run x-ui-latest.sh — install only the utility, then restore a trusted archive:
curl -fSL https://raw.githubusercontent.com/xPROMSx/3x-ui-auto-nginx/main/assets/backup/x-ui-backup.sh -o /tmp/x-ui-backup
install -o root -g root -m 0755 /tmp/x-ui-backup /usr/local/bin/x-ui-backup
rm -f /tmp/x-ui-backup
x-ui-backup restore /root/<archive>.tar.gzSSH, OS configuration, and the base firewall remain the administrator's responsibility. For v2 archives, use the utility from the matching older release.
This project is based on 3x-ui-pro by mozaroc. It grew out of a fork of x-ui-pro and traces back to the original x-ui-pro by GFW4Fun. This project is now maintained independently. Since the fork, nginx/SNI routing and XHTTP configuration have been substantially reworked, TLS certificate issuance and automatic renewal redesigned, and Backup / Restore v3 introduced with recovery and rollback capabilities. Hysteria2 on UDP/443 was added, and identified security issues were fixed.
The panel comes from MHSanaei/3x-ui. Third-party authors retain their rights and existing licenses.
Original xPROMSx developments and changes are offered under GNU GPL-3.0-only. Copyright (C) 2026 xPROMSx contributors. The license covers only our rights in those materials; it does not relicense inherited code or establish GPL status for the entire repository. The scope of our license and notices for third-party components are explained in THIRD_PARTY_NOTICES.md.
If you want to reuse our code. You don't need to do anything to install or use this project; it's still free. If you publish your own version or reuse our code in another project, keep the credit © xPROMSx · github.com/xPROMSx/3x-ui-auto-nginx in the README and, if your project has an interactive installer, on its start screen or main menu. Clearly state that your version has been modified. Don't present our work as your own. Full terms: docs/NOTICE.md.
If you see two-letter country codes (FI, DE, US) instead of flags when opening the 3x-ui panel in Chrome, Edge, or Brave on Windows 11, try our small companion project Flag Emojis Windows Installer. It restores flag emoji display, preserves the original Windows font, and lets you roll back the change.
If you find this project useful, you can voluntarily support its continued development. The project and all its features remain free and open source, regardless of donations.
- 🌍 International: Support via Tribute (bank card)
- 🇷🇺 Russia: Support via SBP / Mir (bank app)
- All donation methods — including USDT, USDC, and Bitcoin.
Two domains. A few minutes. Your own 3x-ui / Xray server.
⭐ If this installer helped you, consider giving it a Star on GitHub. It helps others discover the project.
