Derek Cameron

Install and configure 3X-UI on Debian Linux VPS

October 11, 2026

We are all connected. The human urge for free communication is entirely natural and deeply rooted in our biology and evolution.

3X-UI is a response to that need. It allows easy management of proxy servers through which individuals can access the global internet. VLESS Reality is a particular protocol that 3X-UI implements. It disguises the proxied traffic as normal HTTPS web browsing.

This page offers an introductory tutorial on using the 3X-UI graphical user interface to configure a VLESS Reality proxy server. The tutorial is a translation and update of material from the blog post at https://v2rayssr.com/me-reality.html

Selection of VPS

Beginners often select a VPS based on the CPU, memory, hard disk size, and price. The reality is that only a small VPS is necessary for a single-user proxy server. A far more important factor is the route to your server.

For China, it is recommended to choose a provider who offers China Telecom Next Carrier Network Global Internet Access (CN2-GIA). This is China Telecom's highest-tier enterprise backbone network, providing premium, low-latency, and bidirectional optimized routing between international servers and mainland China. The price of CN2-GIA servers will be higher, but having a high-quality route to the server is far more important than simply getting the biggest possible server at the lowest possible cost.

BandwagonHost is a popular choice for VPS provider. BWH calls its best connection for China CN2 GIA ECOMMERCE. This uses China Telecom AS 4809 CN2-GIA, combined with China Mobile CMIN2 and China Unicom premium pathways, to reduce lag and packet loss for users connecting from mainland China.

Selection of operating system

It is recommended that you choose Debian 13 ("Trixie"), released in August 2025. If your VPS came with a different operating system, rebuild it with the preferred operating system.

Connect to your VPS with SSH

Connect to your VPS via SSH using the following command in the Terminal (Linux or macOS) or PowerShell (Windows).

If the SSH port is the default 22, use:

ssh root@YOUR.SERVER.IP.ADDRESS

If the SSH port is not the default 22, e.g. the port is 2200, then use:

ssh root@YOUR.SERVER.IP.ADDRESS -p 2200

Update server

Get your server's existing software packages and metadata up to date.

apt update && apt upgrade -y

Enable BBR acceleration

Enable the "Bottleneck Bandwidth and Round-trip propagation time" (BBR) algorithm for congestion control:

echo "net.core.default_qdisc=fq" >> /etc/sysctl.conf

echo "net.ipv4.tcp_congestion_control=bbr" >> /etc/sysctl.conf

sysctl -p

Verify that BBR is successfully turned on:

sysctl net.ipv4.tcp_congestion_control

lsmod | grep bbr

Open firewall

Open your server firewall for input on these ports:

tcp/80 – for SSL certificate issuance
tcp/443 – for VLESS Reality input
One other high-numbered port in the range 20000–60000 – for accessing the 3X-UI panel

Download and invoke the 3X-UI installation script

The 3X-UI panel is recommended because it has no advertising, the interface is clean and beautiful, and the installation and configuration stages are all in English. The 3X-UI panel's official project address is https://github.com/MHSanaei/3x-ui.

Enter this command in your SSH session with your server to download and run the script:

bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

If you get a message -bash: curl: command not found, it indicates that curl is not installed on the system. Use the following command to install it:

apt update && apt install -y curl

The blogger has written a version of the 3X-UI installation script with the messages translated into Chinese. 中文版项目地址： https://github.com/V2RaySSR/3x-ui-cn-installer.

安装命令如下：

bash <(curl -fsSL https://raw.githubusercontent.com/V2RaySSR/3x-ui-cn-installer/main/install-cn.sh)

Answer the 3X-UI installation script's questions

The script will ask you to confirm or override its choices for parameters:

You are asked to select a database for storing client details. SQLite is the default and is recommended if you will have less than 500 clients. PostgreSQL is recommended for high client counts and/or many nodes.
You are asked to select a Panel Port, or allow the script to choose a random one for you. This port must be open for TCP input in your server's firewall.
Your SSL options are Let's Encrypt for domain (90-day validity, auto-renews), Let's Encrypt for IP Address (6-day validity, auto-renews), custom SSL Certificate (path to existing files), or skip SSL (advanced — behind reverse proxy / SSH tunnel only). The default is option 2, an SSL certificate for your IP address. This does not require you to buy a domain name.
You are asked to confirm that the script has the identified correct incoming public IPv4 address for this server.
You are asked if you also want IPv6 accessibility.
You are asked which Port to use for the ACME HTTP-01 listener (default 80).
The IP certificate is installed and configured. The certificate is valid for ~6 days, and auto-renews via acme.sh cron job. The acme.sh script will automatically renew and reload it before expiry.
The script displays the 3X-UI panel Username, Password, Port, WebBasePath, Database, Access URL, and API Token.
Save these credentials securely!

Example:

═══════════════════════════════════════════
     Panel Installation Complete!
═══════════════════════════════════════════
Username:    ByCFhAi2uG
Password:    8ORNYiIeno
Port:        49936
WebBasePath: JpFvAEncGmlgpXX7T2
Database:    SQLite (/etc/x-ui/x-ui.db)
Access URL:  https://YOUR.SERVER.IP.ADDRESS:49936/JpFvAEncGmlgpXX7T2
API Token:   fCJrTPtfsF4iYoULubXt8IUsTC4JTSfkYZqxhNz7ttEJFA48
═══════════════════════════════════════════

At the end of the script's run, it displays the 3X-UI control menu subcommands:

┌───────────────────────────────────────────────────────┐
│  x-ui control menu usages (subcommands):              │
│                                                       │
│  x-ui              - Admin Management Script          │
│  x-ui start        - Start                            │
│  x-ui stop         - Stop                             │
│  x-ui restart      - Restart                          │
│  x-ui status       - Current Status                   │
│  x-ui settings     - Current Settings                 │
│  x-ui enable       - Enable Autostart on OS Startup   │
│  x-ui disable      - Disable Autostart on OS Startup  │
│  x-ui log          - Check logs                       │
│  x-ui banlog       - Check Fail2ban ban logs          │
│  x-ui update       - Update                           │
│  x-ui legacy       - Legacy version                   │
│  x-ui install      - Install                          │
│  x-ui uninstall    - Uninstall                        │
└───────────────────────────────────────────────────────┘

Log in to the 3X-UI panel

Open a browser on your PC.

Navigate to the panel URL and port given by the installation script, e.g. https://YOUR.SERVER.IP.ADDRESS:49936/JpFvAEncGmlgpXX7T2.

Enter the Username and Password generated by the script.

Add your first Inbound

Click the Inbounds menu item in the sidebar, then click Add Inbound.

On the Basics tab:

Enabled	On
Remark	Anything you want, but it is used to identify the Inbound, so you will need to know it when you add the Client in the next step
Protocol	`vless`
Address	Leave blank to listen on all IP addresses
Share address strategy	`Inbound listen`
Subscription sort order	`1`
Disable XTLS flow	Off
Port	`443`
Total Flow	`0`
Traffic Reset	`Never`
Duration	Blank

On the Protocol tab:

Decryption	`none`
Encryption	`none`
Generate keys	`X25519 (native)`

On the Stream tab:

Transmission	`RAW`
Proxy protocol	Off
HTTP Obfuscation	Off
Sockopt	Off
TCP Masks	None

On the Security tab:

Security	Reality
Show	Off
Xver	0
uTLS	`chrome`
Target	`www.apple.com:443` (or use the Find Targets button)
SNI	`www.apple.com` (must match the Target)
Max time diff (ms)	0
Min client ver	Blank
Max client ver	Blank
Short IDs	Automatically generated
SpiderX	Automatically generated
Public key	Automatically generated
Private key	Automatically generated
mldsa65 Seed	Blank
mldsa65 Verify	Blank
Master Key Log	Blank

On the Sniffing tab:

Enabled	On
Protocols	HTTP, TLS, and QUIC
Metadata Only	Off
Route Only	On
IPs excluded	Blank
Domains excluded	Blank

(Sniffing is a feature in inbound proxy configurations that inspects early connection data to extract domain names and application protocols.)

Click Create.

Add your first Client

Now in the sidebar choose the Clients menu item, then click Add Client.

On the Basics tab:

Email	On
Traffic Limit (GB)	`0`
IP Limit	`0`
HWID Limit	`0`
Expiry	Blank
Start after first use	Off
Auto Renew (days)	`0`
Renew on day	`0`
Max renewals	`0`
Traffic Reset	`Never`
Comment	Blank
Group	Blank

Attach by name the Inbound you added in the previous step.

On the Credentials tab:

UUID	Automatically generated
Password	Automatically generated
Subscription ID	Automatically generated
Hysteria Auth	Automatically generated
Flow	`xtls-rprx-vision`

Click Create.

Export URL

On the row for the Client you just added, click the information symbol ⓘ.

Scroll down and under Copy URL, click the copy icon button.

This copies the VLESS URL to your clipboard. It will look something like this example: vless://26a803a1-7118-45f8-beb0-c63aafa2ceef@YOUR.SERVER.IP.ADDRESS:443?encryption=none&fp=chrome&pbk=U51sg....

Install and configure client software

Now you need to install and configure the client software on your client device(s). If you are completely new to Xray, consult the list of available GUI clients at https://github.com/XTLS/Xray-core#gui-clients.

The most popular client on Windows is v2rayN. Its Releases page is at https://github.com/2dust/v2rayN/releases.

In brief:

From the v2rayN Releases page, download the Asset v2rayN-windows-64.zip (again, we are assuming your PC runs Windows).
Extract the zip file.
Run the extracted executable v2rayN.exe.
If the Microsoft Defender SmartScreen box appears saying that Windows protected your PC, click Run anyway.
Click Configuration > Import Share Links from Clipboard to paste the VLESS URL you copied to your clipboard from the 3X-UI panel.
v2rayN listens locally on 127.0.0.1 port 10808.
Set the system proxy.
Open a browser.
Visit a page that will allow you to check that you are now browsing the web via your remote proxy server.

Support

Instructions for 3X-UI are available in multiple languages on the README page at https://github.com/MHSanaei/3x-ui.
If you need to report an issue with 3X-UI, the project has an Issues tab.
There is a list of Xray GUI clients on the README page at https://github.com/XTLS/Xray-core.
If you need to report an issue with Xray, that project also has an Issues tab.
There is an Xray Telegram group at https://t.me/projectXray