Amnezia Web Panel

A modern, high-performance web interface for managing AmneziaWG, Classic WireGuard, Xray (XTLS-Reality), Telemt (Telegram MTProxy), Cloudflare WARP, AmneziaDNS, AdGuard Home, SOCKS5, NGINX + Let's Encrypt and exit nodes (entry ≠ egress) 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.

Additional Sections

🚀 Key Features

• ⚡ Protocols:

• 🛠 Services:

• ⚙️ Core Server Management:

• 🧩 Marketplace & Templates:

• 🌐 Internationalization (i18n):

• 👥 Advanced User Management:

• 🎨 Premium UI/UX:

• 🤖 Telegram Bot Integration:

• 🔄 Built-in Update Checker:

• 📤 Data Interoperability:

• 📧 Email Delivery of Configurations:

• 🔗 Public Sharing:

• 🔐 Self-Service Security:

• 🌍 One-click Public Tunnels:

• 🔑 API Tokens for External Integrations:

💡 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!

🏗 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:

git clone https://github.com/PRVTPRO/Amnezia-Web-Panel.git
    cd Amnezia-Web-Panel

1. Set up Virtual Environment:

python -m venv venv
    source venv/bin/activate  # Windows: venv\Scripts\activate

1. Install Dependencies:

pip install -r requirements.txt

🚀 Getting Started

Launch the application:

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 Image

https://hub.docker.com/r/prvtpro/amnezia-panel

Images are also published to GitHub Container Registry on every push to main and on every v* tag:

# Panel
docker pull ghcr.io/prvtpro/amnezia-panel:latest
Panel with Cloudflare WARP inside the container
docker pull ghcr.io/prvtpro/amnezia-panel:latest-warp

The bundled docker-compose.yml sets DATA_FILE=/app/data/data.json so panel state lands on the amnezia_data volume and survives container rebuilds — see Environment Variables for the full list of knobs.

AWG connections created through the admin user-connection endpoint also use .peer-creates.json. Keep this mode-0600 operation journal on the same persistent volume and include it in filesystem backups alongside data.json. It contains private key material; do not publish it. The JSON settings export is not a substitute for this backup. Run one panel process, as required by the in-process mutation/data locks. Retry the same operation_id after an uncertain response; the standard user-connection dialog retains it until success.

Initial Login

• Username: admin
• Password: admin

Secure your panel by changing the default password in the Users section immediately after first login.

🧰 Environment Variables

Every variable is optional — the panel starts with working defaults. Paths marked resolve next to app.py, or next to the executable in the standalone builds from Installation Method 2.

| Variable | Default | Purpose | | --- | --- | --- | | SECRET_KEY | random on each start | Key used to sign session cookies. Without it a fresh key is generated at every start, which logs all admins out on restart — set a long random value in production. | | DATA_FILE | /data.json | Path to the JSON state file (servers, users, API tokens, settings). ~ is expanded and missing parent directories are created on first save. | | TUNNEL_STATE_FILE | /tunnels_state.json | Path where Cloudflare/ngrok tunnel runtime state (PID, public URL) is persisted between restarts. | | TUNNEL_BIN_DIR | /bin | Directory holding the panel-managed cloudflared / ngrok binaries downloaded from the Settings page. | | AWG_IPV6 | auto | Dual-stack policy for AWG tunnels: auto probes the host and the protocol container, off keeps every tunnel IPv4-only, on forces dual-stack. |

Two things that are deliberately not environment variables: the port the panel listens on and its SSL certificates, both configured in Settings → SSL and stored in the state file. For ngrok, the authtoken comes from Settings as well and overrides an inherited NGROK_AUTHTOKEN.

Running from source or from a binary:

export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_hex(32))')"
export DATA_FILE=/var/lib/amnezia-panel/data.json
python app.py

With Docker, pass the same variables through -e:

docker run -d \
  -p 5000:5000 \
  -e SECRET_KEY=change-me \
  -e DATA_FILE=/state/data.json \
  -v panel_state:/state \
  ghcr.io/prvtpro/amnezia-panel:latest

Docker Compose additionally reads these from your shell or from an .env file next to docker-compose.yml. They configure Compose itself rather than the panel process:

| Variable | Default | Purpose | | --- | --- | --- | | APP_PORT | 5000 | Host port published for the panel container. | | DATA_FILE | /app/data/data.json | Forwarded into the container; keep it under /app/data so state stays on the amnezia_data volume. |

🔧 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)

| 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:

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
Publish an instance on another address (empty fields reset it to the server's own)
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"protocol":"telemt","public_host":"203.0.113.9","public_port":"443"}' \
  http://your-panel:5000/api/servers/0/protocol/public-endpoint

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: Local JSON storage (data.json, path overridable via the DATA_FILE environment variable) with an asyncio.Lock for thread-safe writes
• SSH Engine: Paramiko

Project Structure

web-panel/
├── app.py                    # FastAPI entry point + all routes
├── exit_link_service.py      # Link / unlink / failover between entry and exit nodes
├── exit_failover.py          # Health, thresholds and failback policy (no SSH)
├── telegram_bot.py           # Optional Telegram bot integration
├── mail_service.py           # SMTP delivery of configs/links (single and bulk)
├── 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)
│   ├── telemt_manager.py     # Telegram MTProxy
│   ├── dns_manager.py        # AmneziaDNS (Unbound)
│   ├── adguard_manager.py    # AdGuard Home
│   ├── socks5_manager.py     # 3proxy-based SOCKS5
│   └── exit_manager.py       # Exit-node transit endpoint (amnezia-exit)
├── static/                   # CSS / favicon / PWA icons / SW / vendored JS
├── templates/                # Jinja2 templates
├── translations/             # en / ru / fr / zh / fa
├── pwa.py                    # Web app manifest builder
└── data.json                 # Panel state (servers, users, tokens, settings)

🛡 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 (see Environment Variables).
• IPv6: if your servers have global IPv6 but Docker is IPv4-only, leave AWG_IPV6 at auto — the panel probes the container and keeps tunnels IPv4-only rather than blackholing client IPv6. Set AWG_IPV6=off to disable dual-stack everywhere.
• SMTP Password: stored in data.json next to the other credentials. Use a mailbox dedicated to the panel (or an app password), not your personal account, and keep data.json readable only by the user the panel runs as.
• 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.

📱 Progressive Web App (PWA)

The panel is installable as a Progressive Web App on phones and desktops. On mobile (≤768px) you get a compact sticky header, a role-gated bottom tab bar, and touch-friendly controls; QR codes and forms adapt to narrow viewports.

Install

• Android (Chrome / Edge): open the panel over HTTPS, then use the browser menu → Install app / Add to Home screen.
• iOS (Safari): Share → Add to Home Screen. Standalone mode uses a translucent status bar; safe-area insets keep controls clear of the notch.
• After install, the app opens in standalone chrome with shortcuts to Connections (/my) and Users (/users).

HTTPS requirement

Service workers (and therefore installability) require a secure context: HTTPS or localhost. The default docker-compose.yml exposes plain HTTP on port 5000, which is fine for local development but not installable on a remote phone.

To make the PWA installable in production, terminate TLS in one of these ways:

• Enable HTTPS in Settings → SSL (settings.ssl) with a certificate and key (or paste PEM text).
• Put the panel behind a reverse proxy with a real certificate.
• Use the built-in Cloudflare Quick Tunnel or ngrok tunnels from Settings — they provide public HTTPS URLs suitable for install and for sharing the panel.

🤝 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 file for details.