# Amnezia Web Panel A modern, high-performance web interface for managing **AmneziaWG**, **Classic WireGuard**, **Xray (XTLS-Reality)**, **Hysteria 2**, **NaiveProxy**, **Telemt (Telegram MTProxy)**, **Cloudflare WARP**, **NordVPN**, **AmneziaDNS**, **AdGuard Home**, **SOCKS5**, and **NGINX + Let's Encrypt** services on remote Ubuntu servers β€” from a single dashboard. Designed to provide a premium user experience with robust administrative capabilities. > ### πŸ”„ Compatibility with Official Amnezia Client > > This panel is fully compatible with the official **Amnezia** applications! > > **How to connect an existing server:** > 1. Add your pre-configured server by entering its **IP address**, **login** and **password** > 2. Go to the "Added Servers" section > 3. Wait for the automatic server verification > 4. The panel will automatically detect: > - βœ… Installed protocols > - βœ… Existing users > - βœ… Current configuration > > ⚑ **After verification, you can manage the server directly from the panel!** ## ⚠️ Legal Notice > **This project is created solely for educational and research purposes.** > > **This project has never been intended for use in jurisdictions where the technologies employed are prohibited.** The author bears no responsibility for any unlawful use of this software. **This project merely adds an abstraction layer for managing publicly available applications.** All applications belong to their respective owners. This project does not claim ownership over, nor does it modify, any third-party applications. The use of traffic obfuscation tools may violate the laws of your country. Only use this software for lawful purposes, such as: - **Penetration testing and security research** - **CTF (Capture The Flag) competitions** - **Academic and scientific research** - **Testing and securing your own networks** - **Improving defensive security measures** - **Educational training in cybersecurity** > **Nothing in this project constitutes an incitement to violate any applicable laws.** ![Servers Dashboard](https://raw.githubusercontent.com/PRVTPRO/Amnezia-Web-Panel/refs/heads/main/screen/panel1.png) ### Additional Sections
πŸ‘₯ Users Management (click to expand)
User management interface with permissions and access controls: ![Users Management](https://github.com/PRVTPRO/Amnezia-Web-Panel/blob/main/screen/panel1-2.png)
βš™οΈ System Settings (click to expand)
Configuration panel for system parameters and preferences: ![Settings Panel](https://github.com/PRVTPRO/Amnezia-Web-Panel/blob/main/screen/panel1-3.png)
## πŸš€ Key Features * **⚑ VPN Protocols**: * **AmneziaWG (AWG / AWG 2.0 / AWG Legacy)**: Advanced WireGuard-based protocol with S3/S4 obfuscation to bypass deep packet inspection (DPI). Three coexisting variants β€” modern AWG 2.0 with full junk-packet masking, and a legacy variant for older clients. * **Classic WireGuard**: Standard, high-performance WireGuard protocol for unmatched speed and broad device compatibility with traffic monitoring support. * **Xray (XTLS-Reality)**: Stealthy protocol that masks VPN traffic as standard HTTPS browsing. Pinned to **Xray-core v26.x**; transparently reads both the **panel layout** (`meta.json` + `clientsTable.json`) and the **native Amnezia client layout** (`xray_*.key` files + `clientsTable`), so a node first installed via the official mobile/desktop app can be attached to the panel without re-installation. * **Hysteria 2**: QUIC/HTTP3 proxy from [apernet/hysteria](https://github.com/apernet/hysteria) via `tobyxdd/hysteria:v2` β€” Let's Encrypt TLS, salamander obfuscation, password auth, `hy2://` share links. Per-server SSL domain/email defaults, renew from settings; install requires free TCP **80** and **443**. * **NaiveProxy** (stable): HTTPS/HTTP2 camouflage proxy via [klzgrad/naiveproxy](https://github.com/klzgrad/naiveproxy) (Caddy + [klzgrad/forwardproxy](https://github.com/klzgrad/forwardproxy) naΓ―ve fork). ACME TLS on the domain, per-client basic auth, `naive+https://` share links. Requires free TCP **80** and **443**. **Use Karing** as the client β€” do **not** use v2rayN; other clients are untested. * **Telemt (Telegram MTProxy)**: High-performance Telegram MTProxy with TLS emulation and comprehensive management (quotas, IP limits, real-time session tracking). Robust install path that auto-configures Docker's official apt/yum repository when needed. * **Cloudflare WARP**: Add and manage WARP-powered connectivity from the panel for routing and network flexibility. * **NordVPN**: Connect/disconnect outbound NordVPN from Settings via the official CLI (optional country/city). * **πŸ›  Services**: * **AmneziaDNS**: Internal DNS resolver on a private docker network (`amnezia-dns-net`, IP `172.29.172.254`) to prevent DNS leaks and blockings. * **AdGuard Home**: DNS-based ad blocker with a web admin UI. Two install modes: **Replace AmneziaDNS** (takes its IP, all VPN clients use AdGuard immediately) or **Side-by-side** (parallel deployment on `172.29.172.253`, web UI accessible only over the VPN by default). Optional opt-in checkboxes to expose the web UI / DoT / DoH on the host. * **SOCKS5 Proxy**: Single-account 3proxy-based SOCKS5 server modelled after the official Amnezia client. Auto-generated 16-character password on install, port and credentials editable later from the panel without re-install. * **NGINX + Let's Encrypt**: Reverse-proxy and HTTPS automation with certificate management for secure public endpoints. * **βš™οΈ Core Server Management**: * **Add / Edit / Delete / Reorder** server entries β€” drag-and-drop reorder updates `server_id` references in saved connections automatically. * **Per-server SSL defaults**: optional domain + Let's Encrypt email on each server, pre-filled when installing Hysteria or NGINX. * **Live ping indicator** next to each server name β€” non-blocking TCP-connect probe to the SSH port, runs on the asyncio loop in parallel for all servers. * **Clear server** wipes every Amnezia-related container, image and `/opt/amnezia` directory in a single sudo script β€” works for any current or future `amnezia-*` protocol. * **Reboot** the server directly from the UI. * Strictly concurrent protocol status polling β€” all supported protocols/services checked in parallel for immediate feedback. * **Asynchronous Processing**: Resilient, non-blocking background architecture prevents the UI panel from freezing, even if remote endpoints hang. * **🧩 Marketplace & Templates**: * Market templates provide quick presets for installing and configuring supported protocols and services (including **Hysteria 2**). * Multi-protocol management lets you run and control multiple protocol instances on the same server. * **🌐 Internationalization (i18n)**: * Full support for **English**, **Russian**, **French**, **Chinese**, and **Persian**. * Native **RTL (Right-to-Left)** support for Persian language. * **πŸ”„ Auto-update**: * Settings β†’ About checks releases on [git.evilfox.cc](https://git.evilfox.cc/test2/Amnezia-Web-Panel-main) and can install the latest tag via git + restart (when the panel runs from a git checkout). * **🌍 Tunnels & outbound VPN**: * **Cloudflare Quick Tunnel** and **ngrok** expose the local panel to the internet. * **Cloudflare WARP** and **NordVPN** route the host outbound (no public panel URL). * **πŸ‘₯ Advanced User Management**: * Role-based access (Admin, Support, Regular User). * Traffic limits, status monitoring, and account expiration. * One-click user enabling/disabling. * **🎨 Premium UI/UX**: * Stunning glassmorphism design. * Dynamic **Dark/Light** mode transition. * Fully responsive for mobile and desktop. * **πŸ€– Telegram Bot Integration**: * Notify users about new connections or limits. * Integrated management via Telegram commands. * Admin-role workflows for managing servers, protocols, users, and connections directly from Telegram. * **πŸ”„ Built-in Update Checker**: * View your current panel version directly in Settings. * One-click check for fresh GitHub releases to stay up to date. * **πŸ“€ Data Interoperability**: * **Remnawave Sync**: Automatically import and sync users from Remnawave. * **Simple Backup**: Effortless JSON-based export and restore of all panel data. * **Backup / Migrate protocols (Alpha)**: Move protocol configurations between nodes for maintenance, recovery, and migration workflows. * **πŸ”— Public Sharing**: * Generate password-protected links for users to download their configurations without panel access. * **🌍 One-click Public Tunnels**: * Open the local panel to the internet from `/settings` using **Cloudflare Quick Tunnel** or **ngrok**. * Shows the local server URL, installation state, running state, and issued public HTTPS URLs directly in the UI. * Supports one-click install, enable, stop, and delete for panel-managed tunnel binaries. * Persists tunnel PID/public URL state across panel restarts and can detect already running tunnel processes. * Works on Windows, Linux, and Docker-friendly environments; `TUNNEL_BIN_DIR` and `TUNNEL_STATE_FILE` can override binary/state locations. * **πŸ”‘ API Tokens for External Integrations**: * Issue bearer tokens from `/settings` for CI bots, monitoring, or any third-party service. * Panel never stores the raw token β€” only its SHA-256 hash. The full value is shown **once** at creation; lose it and you must rotate. * Tokens inherit the role of the admin who created them and are revoked automatically if that user is disabled or demoted. * Send `Authorization: Bearer ` with any admin endpoint β€” every endpoint that accepts a session also accepts a token, no other changes. ## πŸ’‘ Need Additional Functionality? If you require any custom features not currently available in the panel, **let us know – we'll implement them quickly!** * **Database Support**: PostgreSQL, MySQL/MariaDB, SQLite, Oracle, and MS SQL Server * **In-Panel File Editor**: Edit configuration files inside containers directly from the web interface * **Advanced backup automation**: Scheduled backups, external storage, and richer recovery workflows * **Advanced protocol migration**: Extended migration tooling for complex multi-node setups * **Xray Self-Steal Mode**: Advanced Xray configuration with self-steal functionality * **And much more!** **Or better yet, contribute!** ## πŸ— Prerequisites * **Python 3.10+** * Target servers: **Ubuntu 20.04/22.04/24.04** (Architecture: x86_64 or ARM64). * SSH access to target servers (Password or Private Key). ## πŸ“¦ Installation 1. **Clone the repository**: ```bash git clone https://github.com/PRVTPRO/Amnezia-Web-Panel.git cd Amnezia-Web-Panel ``` 2. **Set up Virtual Environment**: ```bash python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate ``` 3. **Install Dependencies**: ```bash pip install -r requirements.txt ``` ## πŸš€ Getting Started Launch the application: ```bash python app.py ``` The panel will be accessible at `http://localhost:5000`. ## πŸ“¦ Installation Method 2 Download and run the executable file for your system. ``` Windows Linux Mac ``` ## 🐳 Docker **Quick start (panel + PostgreSQL 17):** ```bash cp .env.example .env # set SECRET_KEY and strong POSTGRES_PASSWORD in .env docker compose up -d --build ``` Panel: `http://localhost:5000` (or `APP_PORT` from `.env`). | File | Purpose | | --- | --- | | `Dockerfile` | Production image (Python 3.12) | | `docker-compose.yml` | Panel + PostgreSQL with healthchecks | | `.env.example` | Environment template | **Environment** | Variable | Default | Description | | --- | --- | --- | | `APP_PORT` | `5000` | Host port / in-container listen port | | `SECRET_KEY` | (random) | Session signing key β€” set in production | | `DATABASE_URL` | compose DSN | PostgreSQL connection string | | `POSTGRES_*` | `amnezia` | DB credentials for the `db` service | Prebuilt Hub image (upstream): https://hub.docker.com/r/prvtpro/amnezia-panel ### Initial Login * **Username**: `admin` * **Password**: `admin` > [!IMPORTANT] > Secure your panel by changing the default password in the **Users** section immediately after first login. ## πŸ” CI/CD GitHub Actions workflows in `.github/workflows/`: | Workflow | Trigger | What it does | | --- | --- | --- | | `ci.yml` | push / PR to `main` | Validate translations, `compileall`, Docker build smoke | | `docker.yml` | push to `main` / tags `v*` | Build & push image to GHCR (`ghcr.io//`) | | `build.yml` | push / tags `v*` | PyInstaller binaries (Linux / Windows / macOS) + release assets | ## πŸ“‹ Fix / changelog (this fork) ### v2.5.0 * **NordVPN in Tunnels** β€” connect/disconnect outbound NordVPN from Settings (official `nordvpn` CLI; optional country/city). ### v2.4.0 * **Auto-update from Gitea**: Settings β†’ About checks https://git.evilfox.cc/test2/Amnezia-Web-Panel-main releases and can install the latest tag via `git fetch` + checkout, then restart (git install only). ### v2.3.0 * **Cascade removed** β€” double-VPN feature dropped from the panel (manager, API, UI, i18n). ### v2.2.1 * **Cascade egress verify fix**: bind curl to ENTRY `awg0`/`wg0` IP (client-subnet policy route), not cascade peer Address. * Soft-warn (no rollback) when policy route via `cascade` is OK but public-IP echo services fail. ### v2.2.0 * **Cascade (double VPN) restored** β€” later removed in **v2.3.0**. * Inspired by [ryderams/amneziawg-cascade](https://github.com/ryderams/amneziawg-cascade); logic ran over panel SSH (**no remote curl|bash**). ### v2.1.0 * **NaiveProxy β€” stable**: production-ready install (Caddy + klzgrad/forwardproxy), share links always include `:443`. * **Client notes (important)**: * **Do not use v2rayN** with NaiveProxy (broken DNS/IPv6 behaviour β†’ latency βˆ’1 ms even when the server is fine). * **Karing** β€” confirmed working. * Other clients β€” untested / use at your own risk. * Share-link and config UI hints updated accordingly. ### v2.0.0-beta * **NaiveProxy** (Beta): install [klzgrad/naiveproxy](https://github.com/klzgrad/naiveproxy) server via Caddy + naΓ―ve [forwardproxy](https://github.com/klzgrad/forwardproxy) β€” domain TLS (ACME), per-client basic auth, `naive+https://` share links. * Marketplace / server page / users / invites / Telegram / backups include NaiveProxy. * Install warns that free TCP **80** and **443** are required; uses per-server SSL domain/email defaults when set. * Official prebuilt Caddy on amd64; xcaddy build path for other arches. * Version line bumped to **2.0 Beta** (`v2.0.0-beta`). ### v1.8.0 * **Hysteria 2** fully wired in marketplace, server page, users/invites, Telegram bot, and backups. * **Per-server SSL defaults**: set domain + Let's Encrypt email when adding/editing a server; values pre-fill Hysteria (and NGINX) install forms. * **SSL renew**: change domain or use β€œRenew SSL” in Hysteria settings to re-issue the certificate (needs free TCP 80). * **Install warning**: free TCP ports **80** and **443** required for stable Let's Encrypt / HTTPS-QUIC operation. * Official image `tobyxdd/hysteria:v2`, salamander obfs, password auth, `hy2://` share links, selectable UDP listen port. ### v1.7.0 * **Clearer create flow**: pick **server first**, then **protocol** (WireGuard, AmneziaWG 2.0, …) β€” invites, guest access, and user connections no longer dump everything into one messy list. * Protocol titles are human-readable and ordered (AWG 2.0 β†’ AWG β†’ Legacy β†’ WireGuard β†’ Xray β†’ Telemt β†’ Hysteria). * 3x-ui is a separate β€œserver” choice; VLESS inbounds still load from that panel’s API. * **Hysteria 2** manager restored ([apernet/hysteria](https://github.com/apernet/hysteria)) β€” see **v1.8.0** for full panel integration. ### v1.6.0 * **3x-ui multi-panel**: register several 3x-ui servers in Settings; pick a panel and load VLESS inbounds over its API when creating users/invites (share link comes from 3x-ui). * **Docker / CI**: refreshed `Dockerfile` + compose, `.env.example`, CI checks, GHCR image workflow. * **Cascade** was temporarily removed in this release (briefly restored in v2.2.x, removed again in **v2.3.0**). * **WG/AWG backups**: ZIP export of client `.conf` + restore with loading feedback. * **API performance**: in-memory data cache, faster server check/stats. * **Share / guest**: one-tap β€œCopy key”. * **User expiration**: countdown can start on first config use; UTC-safe comparisons. * **UI**: shared SVG icon system. ## πŸ”§ Project Details ### API Documentation The project includes self-documenting API endpoints, organised into clear tag groups: * **Swagger UI**: `/docs` * **ReDoc**: `/redoc` (pinned to a stable bundle, Google Fonts disabled β€” works on networks where they're blocked) Routes are grouped in the docs as: | Group | Purpose | | --- | --- | | **System Templates** | HTML pages served to browsers (login, server detail, settings, /share). Not part of the JSON API. | | **Authentication** | Login, captcha, session lifecycle. | | **Servers** | Server inventory & host-level operations (add/edit/delete, ping, reorder, reboot, clear, stats). | | **Protocols** | Install / uninstall / container / raw-config editing for every protocol & service on a server. | | **Connections** | Per-protocol VPN client connections (CRUD, enable/disable, fetch config). | | **Users** | Panel user accounts and the connections assigned to them. | | **Self-service** | Endpoints called by a regular user for their own data (`/api/my/*`). | | **Sharing** | Public, token-protected configuration sharing β€” no panel session required. | | **Settings** | Panel-wide settings, Telegram bot, Remnawave sync, JSON backup/restore. | | **API Tokens** | Create and revoke bearer tokens for external integrations. | **Authentication for external integrations** β€” both session cookies and `Authorization: Bearer ` are accepted on every admin endpoint. Example: ```bash TOKEN="awp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # List panel users curl -H "Authorization: Bearer $TOKEN" http://your-panel:5000/api/users # Add a server curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"host":"1.2.3.4","username":"root","password":"...","name":"new-srv"}' \ http://your-panel:5000/api/servers/add # Cheap reachability probe for monitoring curl -H "Authorization: Bearer $TOKEN" http://your-panel:5000/api/servers/0/ping ``` ### Technology Stack * **Backend**: FastAPI (Python), `asyncio` for concurrent SSH/probe work * **Frontend**: Vanilla JS, Jinja2, Custom CSS (Glassmorphism, full set of CSS animations for promo blocks) * **Database**: PostgreSQL 17 (`DATABASE_URL`) with a dict-compatible store API (`db/`) * **SSH Engine**: Paramiko * **Deploy**: Docker Compose (panel + Postgres), optional GHCR image via CI ### Project Structure ``` web-panel/ β”œβ”€β”€ app.py # FastAPI entry point + all routes β”œβ”€β”€ telegram_bot.py # Optional Telegram bot integration β”œβ”€β”€ db/ # PostgreSQL store + schema helpers β”œβ”€β”€ managers/ # Protocol & service managers (one file per protocol) β”‚ β”œβ”€β”€ ssh_manager.py # SSH abstraction (Paramiko wrapper) β”‚ β”œβ”€β”€ awg_manager.py # AmneziaWG / AWG 2.0 / AWG Legacy β”‚ β”œβ”€β”€ wireguard_manager.py # Classic WireGuard β”‚ β”œβ”€β”€ xray_manager.py # Xray-core (VLESS-Reality) β”‚ β”œβ”€β”€ hysteria_manager.py # Hysteria 2 (apernet/hysteria) β”‚ β”œβ”€β”€ naiveproxy_manager.py # NaiveProxy (Caddy + klzgrad/forwardproxy) β”‚ β”œβ”€β”€ telemt_manager.py # Telegram MTProxy β”‚ β”œβ”€β”€ dns_manager.py # AmneziaDNS (Unbound) β”‚ β”œβ”€β”€ adguard_manager.py # AdGuard Home β”‚ β”œβ”€β”€ socks5_manager.py # 3proxy-based SOCKS5 β”‚ └── backup_manager.py # Protocol backup / restore on remote hosts β”œβ”€β”€ static/ # CSS / favicon / vendored JS β”œβ”€β”€ templates/ # Jinja2 templates β”œβ”€β”€ translations/ # en / ru / fr / zh / fa β”œβ”€β”€ Dockerfile # Panel image β”œβ”€β”€ docker-compose.yml # Panel + PostgreSQL └── .github/workflows/ # CI, Docker publish, binary builds ``` ## πŸ›‘ Security Recommendations * **Reverse Proxy**: It is highly recommended to run the panel behind Nginx/Apache with an SSL certificate. * **SSH Keys**: Use SSH keys rather than passwords for connecting to your VPN servers. * **Secret Key**: Set a custom `SECRET_KEY` environment variable for secure session management. * **API Tokens**: Treat each token like a password β€” store it in your integration's secret manager. Revoke it from `/settings` if it leaks or the integration is decommissioned. Rotate periodically; tokens inherit admin rights. ## 🀝 Contributing Contributions are welcome! Please feel free to submit Pull Requests or open Issues for feature requests and bug reports. ## πŸ“„ License This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](../LICENSE) file for details. --- *Built with ❀️ for the Amnezia community.*