Kuzz007
82cc69f5e9
ClientService.Attach deliberately copies one identity's stored AllowedIPs into every WireGuard/AmneziaWG inbound it's attached to in the same call, so the same person gets the same tunnel address on every protocol they use. Its loop calls addInboundClient once per inbound, and each of those independently computes otherTunnelAllowedIPs -- so by the second inbound in the batch, the first inbound's just-written copy of this identity's own address looked like a cross-inbound collision against itself. Real production symptom this caused: detaching then re-attaching a client to both wg and awg failed with "wireguard: allowedIPs entry X is already used by a client on inbound 'awg' (#N)" -- the exact address the identity is supposed to keep, rejected as if it belonged to someone else. Add a selfEmails exclusion to otherTunnelAllowedIPs and populate it from the client(s) being processed at the one real call site. Safe unconditionally: ClientRecord.Email is globally unique, so a match can only ever be this same identity's own entry on a sibling inbound, never a genuine different client's address. Reproduced the underlying mechanism live (manual entry correctly rejected as a cross-inbound collision; fresh auto-allocation correctly avoided a used address) before writing the fix, to confirm the guard itself works and the bug is specifically in how Attach's per-inbound calls interact with it.
English | فارسی | العربية | 中文 | Español | Русский | Türkçe
This is a personal fork of 3X-UI — the advanced, open-source web control panel for Xray-core — with one major addition: native AmneziaWG support, added as a first-class protocol alongside VLESS, VMess, Trojan, and the rest. Everything else 3X-UI already does (multi-protocol inbounds, per-client traffic accounting, subscriptions, multi-node, the Telegram bot) is unchanged and still works exactly as upstream.
This fork exists to run the author's own routers and servers; it isn't trying to replace or compete with the original project. If you're looking for the general-purpose panel, go to MHSanaei/3x-ui — everything below only documents what's different here.
Important
This project is intended for personal use only. Please do not use it for illegal purposes or in a production environment.
What's different in this fork: AmneziaWG
AmneziaWG is WireGuard with an added obfuscation layer (junk packets, randomized padding, magic-header rewriting) designed to defeat DPI-based protocol fingerprinting — the same tunnel, but one that doesn't look like a tunnel on the wire.
- Embedded, not a kernel module. AmneziaWG runs entirely inside the panel process (amneziawg-go over a userspace network stack) — no DKMS build, no Secure Boot conflict, no privileged sidecar container, and nothing to install on the host at all.
- A first-class protocol. An AmneziaWG inbound lives in the same
Inboundtable as everything else, so it gets bulk operations, the QR/config-download modal, and subscription links for free — nothing bespoke to learn. - Full AmneziaWG 2.0 obfuscation — Jc/Jmin/Jmax (junk packets), S1–S4 (packet padding), H1–H4 (magic headers), and the I1 signature packet, all editable per-inbound with a one-click randomize button, plus a 1.x-compatible fallback for older clients.
- Every client's traffic already goes through Xray. No TPROXY, no bridge to opt into: each AmneziaWG inbound relays straight into its own loopback Xray SOCKS5 inbound, so per-client traffic stats, online status, sniffing, and the panel's existing Routing-page rules all just work, exactly like any other protocol — no extra configuration.
- Real
vpn://share links — the per-client copy-link/QR and the subscription endpoint emit the actualvpn://scheme the official AmneziaVPN app expects (base64url of a plain.conf), not an invented URI format it couldn't import. - Temporarily unsupported after this rewrite: distinct per-client public IPv6 addresses and per-client port-forwarding both relied on the old kernel-module's host-level iptables rules, which don't have an embedded equivalent yet. Both are planned fast-follow releases; existing settings for either aren't lost, they're just inert until then.
Other changes in this fork
Smaller fork-specific improvements beyond AmneziaWG land here as they're added:
- Routing rule autocomplete — the Domain/IP fields in the Xray Routing rule editor suggest geosite/geoip categories (e.g. typing "you" suggests
geosite:youtube) built live from whatever.datfiles are actually installed in the Xray bin folder, including custom ones added via the Geodata auto-update feature (e.g.geosite_roscom.dat). Free-text entry still works exactly as before. - Live Speed for AmneziaWG and MTProto — the Speed column used to show
--for AmneziaWG and MTProto (mtg) inbounds/clients even though cumulative traffic totals were correct, since neither runs inside Xray-core's own runtime and so is invisible to its stats API. Both now broadcast live speed alongside every other protocol. - Custom files in
bin/survive updates — a reinstall/update used to wipe the wholebin/folder before re-extracting the release, silently deleting anything hand-placed there (most commonly a custom geoip/geosite file referenced from a routing rule viaext:<file>:<code>) and breaking every inbound at next start. The installer now backs upbin/first and restores only what the new release doesn't ship.
Features
- Multi-protocol inbounds — VLESS, VMess, Trojan, Shadowsocks, WireGuard, AmneziaWG, Hysteria2, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel, and TUN.
- Modern transports & security — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade, and XHTTP, secured with TLS, XTLS, and REALITY.
- 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, 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.
- Outbound & routing — WARP, NordVPN, custom routing rules, load balancers, and outbound proxy chaining.
- Built-in subscription server with multiple output formats and custom page templates.
- Telegram bot for remote monitoring and management.
- RESTful API with in-panel Swagger documentation.
- Flexible storage — SQLite (default) or PostgreSQL.
- 13 UI languages with dark and light themes.
- Fail2ban integration for enforcing per-client IP limits.
Screenshots
Click to expand
Quick Start
curl -fsSL https://raw.githubusercontent.com/Kuzz007/3x-ui/main/install.sh | bash
To install a specific version, append its tag (e.g. v3.5.0-awg.1):
curl -fsSL https://raw.githubusercontent.com/Kuzz007/3x-ui/main/install.sh | bash -s v3.5.0-awg.1
To install the rolling dev build (latest per-commit pre-release from main, not a stable release), pass dev:
curl -fsSL https://raw.githubusercontent.com/Kuzz007/3x-ui/main/install.sh | bash -s dev
This fork's own stable releases are tagged <upstream base version>-awg.N (e.g. v3.5.0-awg.1, built on top of what upstream calls v3.5.0) — never a bare vX.Y.Z — so they're never mistaken for a real upstream MHSanaei/3x-ui release of the same number.
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.
For general panel documentation beyond what's in this README, see the upstream project Wiki — none of it is fork-specific, so it still applies.
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)
- Hetzner Cloud notes — cloud-init deployment on Hetzner
Supported Platforms
Operating systems: Ubuntu, Debian, Armbian, Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux, Virtuozzo, Arch, Manjaro, Parch, openSUSE (Tumbleweed / Leap), and Alpine. (Upstream also publishes a Windows build; this fork's CI doesn't — everything here targets Linux servers/routers.)
Architectures: amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x.
AmneziaWG is embedded in the panel binary itself (see What's different in this fork) — no kernel module, no separate install step, no distro-specific setup.
Database Options
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):
XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
Migrating an existing SQLite install to PostgreSQL
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1: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.
Environment Variables
| Variable | Description | Default |
|---|---|---|
XUI_DB_TYPE |
Database backend: sqlite or postgres |
sqlite |
XUI_DB_DSN |
PostgreSQL connection string (when XUI_DB_TYPE=postgres) |
— |
XUI_DB_FOLDER |
Directory for the SQLite database file | /etc/x-ui |
XUI_DB_MAX_OPEN_CONNS |
Maximum open connections (PostgreSQL pool) | — |
XUI_DB_MAX_IDLE_CONNS |
Maximum idle connections (PostgreSQL pool) | — |
XUI_INIT_WEB_BASE_PATH |
The initial URI path for the web panel | / |
XUI_ENABLE_FAIL2BAN |
Enable Fail2ban-based IP-limit enforcement | true |
XUI_LOG_LEVEL |
Log verbosity (debug, info, warning, error) |
info |
XUI_DEBUG |
Enable debug mode | false |
XUI_TUNNEL_HEALTH_MONITOR |
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 |
Supported Languages
The panel UI is available in 13 languages:
English · فارسی · العربية · 中文（简体） · 中文（繁體） · Español · Русский · Українська · Türkçe · Tiếng Việt · 日本語 · Bahasa Indonesia · Português (Brasil)
Developer notes
This is a personal fork and isn't looking for outside contributors, but CONTRIBUTING.md still has accurate, useful local dev-setup instructions (Go/Node versions, the C compiler CGo needs, build/lint/test commands) if you're working on this codebase yourself.
Credit
This fork is built entirely on top of MHSanaei/3x-ui — all of the panel, the multi-protocol support, and the underlying architecture is their work; AmneziaWG support is the only thing added here. If you find the base project useful, the original author's support links are still the right place for it:
The AmneziaWG implementation in this fork was ported from/inspired by:
- amnezia-vpn/amneziawg-go — the userspace AmneziaWG implementation this fork embeds directly in the panel process, over a gVisor network stack, replacing the original kernel-module-based backend below.
- MHSanaei/3x-ui#6086 — the original AmneziaWG PR against upstream (Docker-sidecar approach); this fork reuses its frontend schema/UI structure.
- coinman-dev/3ax-ui — an independent fork already running native AmneziaWG in production; this fork's original kernel-module (
awg-quick) manager and AmneziaWG 2.0 obfuscation parameter generator were ported from itsawg/package before this rewrite.
Acknowledgment
- alireza0
- 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.