How to Install 3x-ui and Secure the Panel: 8 Steps

21 Nov 2026 By ST Muntaha
How to Install 3x-ui and Secure the Panel: 8 Steps

You have a server, a few paying users and a plan to run 3x-ui as the panel for Xray. The script does the install in one run. The hour after it decides whether your admin panel sits on the open internet over plain HTTP.

To install 3x-ui safely, pin a release, read the installer before running it, then replace the generated login, confirm TLS is really on, keep the panel off the public network and take a backup before adding users. The steps below come from the v3.11.0 source and docs, read on 31 October 2026. We ran every step except public certificate issuance on v3.11.0 in a throwaway Debian 12 server container on 10 November 2026, including a certificate renewal against a local test CA. Still rehearse on your own server before production. The project’s README says 3x-ui is for personal use only and not for a production environment. Nothing here changes that.

Before You Start

  • A fresh Linux server you can wipe, and root access. The installer exits for any other user.
  • Outbound access to github.com and raw.githubusercontent.com, where the script fetches the release and its helper.
  • For a domain certificate: a DNS record pointing at the server and port 80 free.
  • A password manager and a place off the server for backups.

Plan five kinds of port: SSH, the panel, the subscription server (2096 by default), your inbounds and port 80 for certificate validation. As of 31 October 2026 the latest tag is v3.11.0, published 25 October 2026. The project’s security policy says only the latest release gets security fixes.

Step 1: Choose Script or Docker and Fix the Version

Script Docker (Compose file)
Panel address Random port (1024 to 62000), 18 character path Port 2053, path /
First login Random, printed and saved to /etc/x-ui/install-result.env Random, printed once in the container log
TLS Menu offers domain, IP, custom or skip None until you add it
Updates x-ui update or the pinned script Pull the image and recreate, per the docs
Firewall ufw rules apply Published ports bypass ufw

Docker’s packet filtering page says published ports bypass ufw rules, and the Compose file publishes 2053 without an address. Its port publishing page shows docker run -p 127.0.0.1:8080:80 for loopback only, and the Compose Specification’s short syntax takes the address first, as in 127.0.0.1:2053:2053. We tested neither. The repository’s Compose file builds the image from source, so check which image you run before following the docs’ pull step. Pick the script for one server you manage by hand.

Confirm your tag exists, and avoid dev-latest, which the docs call a rolling pre release:

git ls-remote --tags https://github.com/MHSanaei/3x-ui.git | grep v3.11.0

You know it worked when the tag prints. The usual failure is installing “latest” and getting a different version months later.

Step 2: Read the Script, Then Install 3x-ui

The README runs the script straight from curl. Save it, read it, then run it:

# Throwaway server, as root. Use your chosen tag.
curl -fLo install.sh https://raw.githubusercontent.com/MHSanaei/3x-ui/v3.11.0/install.sh
less install.sh
bash install.sh v3.11.0

Reading install.sh at v3.11.0, we found that it:

  • installs cron, curl, tar, tzdata, socat, ca-certificates and openssl with your package manager;
  • downloads the release archive and checks it against the .sha256 file beside it, aborting on a mismatch;
  • stops the service, deletes /usr/local/x-ui, extracts the archive and restores custom files you had in bin/, leaving /etc/x-ui alone;
  • generates a random 10 character username and password, then asks for SQLite (labeled “recommended for < 500 clients”) or PostgreSQL;
  • queries public IP lookup services, up to six in order, to print the access URL and suggest the address for an IP certificate;
  • for certificate options 1 and 2, installs acme.sh with curl -s https://get.acme.sh | sh, a second script;
  • sets up Fail2ban for the IP limit feature and installs a sandboxed systemd unit.

You know it worked when it prints the credential block and x-ui status shows the service running. The likely failure is unattended mode. With XUI_NONINTERACTIVE=1, or any run without a terminal, an unset XUI_SSL_MODE means no TLS, and the script comments say the panel stays on the public interface.

Step 3: Replace the First Login Details

If you skipped TLS in the installer, finish Step 4 or Step 5 before you log in: the installer warns that credentials and cookies then travel as plain HTTP.

/etc/x-ui/install-result.env holds the username, password, port, path and XUI_API_TOKEN. That token has admin scope and never expires; the script mints it with no expiry. Copy the values into your password manager, then delete the file unless cloud init reads it.

In Panel Settings, set a long unique password, then enable two factor authentication (TOTP). Do it in that order: the docs say changing the username or password logs everyone out and turns 2FA off. The login limiter blocks an IP and username pair for 15 minutes after 5 failures in 5 minutes, but it is kept in memory and keyed by that pair, so it slows one source and is no replacement for a strong secret.

Under Settings, API Tokens, delete or disable the install token unless something uses it. For uptime checks, create a monitor token instead: its allowed routes are a short read only list of status and metrics routes.

You know it worked when login asks for a 6 digit code and the token list shows only tokens you made. If you lose the authenticator, the binary has /usr/local/x-ui/x-ui setting -resetTwoFactor.

Step 4: Turn On TLS and Check It Stayed On

Prefer a domain certificate for anything users touch: x-ui menu 20, then Get SSL (Domain). The IP certificate option is short lived, about six days by the script’s own text, so it suits first access before DNS is ready. The default reload command after a renewal is a restart of the x-ui service, and in our reading connected users briefly reconnect, because the panel’s normal shutdown also stops Xray.

The trap is in the source. If the certificate cannot be loaded, the panel logs an error and serves plain HTTP instead of refusing to start. The subscription server does the same. Check the log after every install, renewal and update:

journalctl -u x-ui --no-pager | grep -E "Web server running|Sub server running|Error loading certificates"

You know it worked when you see Web server running HTTPS. Do not trust the installer’s closing banner: in our reading it can still print an https URL and “SSL Certificate: Enabled and configured” after a failed certificate request. Likely failures are DNS not yet pointing at the server and something else holding port 80. The domain flow prints “Issuing certificate failed, please check logs”; the IP flow asks you to check port 80. Retry from x-ui menu 20. A reverse proxy is the documented alternative; keep the web base path behind it too.

Step 5: Limit Who Can Reach the Panel

The strongest option is no public panel at all. Menu 24, or /usr/local/x-ui/x-ui setting -listenIP 127.0.0.1 followed by x-ui restart, binds the panel to loopback. In our reading menu 24 only reports the panel as secure once a certificate is set, so after Step 4 use the command. The installer and menu 24 print the tunnel:

ssh -L 2222:127.0.0.1:<panel-port> root@<server-ip>
# then open http://localhost:2222/<web-base-path>

That http address fits a panel with no certificate; with one set, use https and expect a name warning for localhost. The subscription server has its own listen address, so this does not close port 2096. For the firewall, menu 23 wraps ufw. Read what Install Firewall does first. If ufw is not already active, it allows the ssh, http and https services plus ports 2053 and 2096, then force enables ufw; if ufw is already active, it changes nothing. After a script install your panel port is random, so run ufw allow <port>/tcp for it, and for SSH if it is not on port 22, before you let the menu enable ufw. Test from a second session.

You know it worked when the panel port no longer answers from another network. The usual failure is a locked out admin, which is why the second session matters. Where you must expose it, restrict the source addresses at your firewall.

Step 6: Close the Subscription and Token Gaps

The subscription server runs by default on 2096, on all addresses, over HTTP unless subCertFile and subKeyFile are set. Fresh databases get random 16 character subscription paths. Setting the panel certificate with x-ui cert, which the installer and menu 20 use, also fills subCertFile and subKeyFile, and the log then shows Sub server running HTTPS. Still set subDomain, or turn the server off if your app never uses it.

v3.8.5 fixed a subscription URL exposure. Its notes say responses no longer link to the built in profile page, which showed the subscription URL, and that page is now opt in. The subProfileMode setting takes none (default), builtin or custom. In the default mode, a fetched subscription URL should carry no Profile-Web-Page-Url header, so check for it. Treat the Sub ID as a password; our guide to VPN subscription URL formats covers leak handling.

The Telegram bot is off by default. If you enable it, add only your own numeric ID as admin, keep the token secret, and keep login.attempt alerts on. The tgBotBackup option sends the database and the Xray config to the chat, and both hold client credentials, so that chat becomes a credential store.

Step 7: Back Up Before the First User

Back up /etc/x-ui/x-ui.db, the certificates under /root/cert/, and the service environment file (/etc/default/x-ui on Debian and Ubuntu) if you chose PostgreSQL, where the panel’s Backup & Restore writes a pg_dump file. The source runs SQLite in WAL mode by default, and SQLite’s WAL documentation says the WAL file should travel with the database when copied. The panel’s own backup uses SQLite’s backup API, which SQLite’s corruption guide lists as safe on a live database, so prefer it. The docs show a plain cp; if you use it, run x-ui stop and copy any x-ui.db-wal and x-ui.db-shm too. We tested this on v3.11.0: after x-ui stop, x-ui.db-wal and x-ui.db-shm were still there, and a copy of x-ui.db alone was missing the newest inbound.

Rehearse the restore on a second throwaway server: stop the panel, delete any old x-ui.db-wal and x-ui.db-shm, put the file back, start it. The guide warns against overwriting a database without deleting its old hot journal; we reproduced it: putting an older x-ui.db back beside the live -wal and -shm files showed the live state, not the backup. Two documented commands do not match the script. The docs show x-ui setting and x-ui migrate-db, but the x-ui helper in v3.11.0 has cases named settings and migrateDB and none named setting or migrate-db, and the binary’s restore also needs --out. Use the binary directly or x-ui migrateDB, and test it.

You know it worked when the restored panel shows your users. The docs advise restoring onto the same major version.

Step 8: Update With the Core Pairing in Mind

x-ui update fetches update.sh from the main branch, installs whatever GitHub reports as the latest stable release, and takes no backup. To control the version, read the pinned install.sh and run it again, which the FAQ says updates in place. The update replaces the Xray binary with the one bundled in the release, so a core you installed from the panel is replaced. The bundled core, from each tag’s release.yml:

Panel release Bundled Xray
v3.8.5 26.9.9
v3.9.0 26.9.30
v3.10.0, v3.10.2 26.10.10
v3.11.0 26.10.21

You may have read that 3x-ui 3.10 needs Xray 26.9.9. We could not confirm that. The v3.10.0 notes give 26.9.9 as the minimum core for client apps that read the udphop port hopping mask in JSON subscriptions, ask owners to move users of port hopping or xdns to client builds on Xray core 26.10.10 or newer, and list 26.10.10 as the core for that release. The same notes say to upgrade every node, describe a service sandbox that makes /usr, /boot, /etc, /home and /root read only except the panel’s own folders, and warn that a failed automatic rewrite stops the panel from starting. See Xray and sing-box breaking changes for the core side.

You know it worked when /usr/local/x-ui/x-ui -v shows the new version, the log shows HTTPS again and a test client connects; our VLESS config test guide covers that check. If the panel will not start, restore the backup you took.

What Should You Check After Install?

Symptom Likely cause Check
Panel opens on http:// No certificate, or the load failed and it fell back The journalctl line in Step 4
Locked out after ufw Install Firewall opens a fixed set of ports ufw status numbered, open your real ports
Certificate request fails DNS not pointing yet, or port 80 in use Free port 80, retry from x-ui menu 20
Ban never applied in Docker Fail2ban needs NET_ADMIN and NET_RAW --cap-add flags or the Compose cap_add
Panel will not start after update An automatic rewrite failed (v3.10.0 notes) Log, then the pre update backup
x-ui setting prints usage The helper has no setting case The binary path from Step 3

FAQ

Is 3x-ui safe to use for paying customers?

The project says it is not intended for production use, so the risk is yours. Hardening reduces exposure but does not change that statement. Keep your own record of customers and a tested backup. If you are still choosing a panel, read our comparison of 3x-ui, Marzban, Hiddify and Remnawave.

What is the default 3x-ui port and password?

The stored default port is 2053 with web base path /. A script install randomizes the port, path, username and password. Docker keeps 2053 and prints a random login once.

Do I need a domain to run 3x-ui?

No. You can use a six day IP certificate, or bind the panel to loopback and use an SSH tunnel. For user facing subscriptions, a domain certificate is the better fit.

How do I reset the 3x-ui password or 2FA?

Run x-ui and choose 7, Reset Username & Password, which asks whether to disable 2FA. The binary also has setting -resetTwoFactor.

How often should I update?

Update when a security fix ships, because only the latest release is patched. Read the release notes, back up, and rehearse on a staging copy first.

Takeaway

Treat the first hour as part of the install: a login only you hold, TLS you confirmed in the log, a panel unreachable from the open internet, and a restore you have actually tried.

DigitalD.tech does not run 3x-ui or other open source panels for clients; we build our own admin panel and custom ones for VPN products. Running a panel for paying users and want a second pair of eyes on the setup, or thinking about a panel of your own? Tell us what you run and what your users need on the contact page, and we will tell you which checks we would run first.

Last checked against the 3x-ui v3.11.0 source, docs and release notes (v3.8.5, v3.10.0, v3.11.0), Docker’s packet filtering and port publishing docs, the Compose Specification, and SQLite’s WAL documentation and corruption guide on 31 October 2026.