aimili-vpngate/docs/README.en.md

AimiliVPN

A VPNGate node manager and HTTP / HTTPS / SOCKS5 proxy gateway for Linux VPS hosts

简体中文 · English · 日本語 · 한국어

Quick install · Installation · Connection · VPS offers · Community · Legal notice

AimiliVPN uses Python's standard library to manage VPNGate nodes. It provides node discovery and testing, connection switching, a Web dashboard, and HTTP, HTTPS website proxying, and SOCKS5 access on one local port.

Item	Default or supported range
Web dashboard	TCP 8787, a private path, username, and password
Local proxy	127.0.0.1:7928, HTTP, HTTPS CONNECT, and SOCKS5
Source deployment	x64, x86, ARM64, and ARM32 Linux
Docker images	linux/amd64, linux/386, linux/arm64, and linux/arm/v7
Update channel	GitHub main stable branch / latest stable Release

Important

Network availability: Some regions, data centers, and network providers may restrict DNS, VPNGate APIs, GitHub mirrors, or VPN protocols. Mirrors and local snapshots improve node-list availability but cannot guarantee a successful connection on every host. Confirm that local law and your VPS provider permit VPN/TUN before deployment.

Quick Install

Run as root on a supported Linux VPS:

bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/main/install.sh)

The installer prints the complete Web URL, private path, username, and password. Run ml to open the management menu.

Tip

Enable TUN/TAP in the VPS control panel and verify that /dev/net/tun exists. The Web dashboard uses TCP 8787 by default; restrict firewall access to your own IP whenever possible.

VPS Offers

The following are affiliate links. Using them does not increase your price.

BandwagonHost Highlights Premium CN2 GIA, China Unicom 9929, and China Mobile CMIN2 optimized routes. Low latency, high stability, and excellent cross-border route quality. Strong connectivity for TikTok live operations, cross-border e-commerce, and long-running global services.

RackNerd Highlights 4000GB of monthly traffic with generous transfer headroom. Affordable pricing and a strong traffic-to-cost ratio. Low deployment cost for services that need to run continuously.

Before purchasing, confirm that the selected plan permits TUN/TAP, OpenVPN, and the required network protocols. An affiliate link is not a guarantee that a specific plan will work.

Installation

Requirements

• Ubuntu, Debian, Alpine, CentOS, RHEL, Rocky Linux, AlmaLinux, Fedora, Oracle Linux, or Amazon Linux.
• root, OpenVPN, iptables, policy routing, and TUN/TAP.
• Windows and macOS can be proxy clients, but cannot run the full gateway. Docker Desktop is not equivalent to a Linux VPS with host TUN access.

Option 1: Source installer

bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/main/install.sh)

The installer deploys to /opt/aimilivpn and registers a system service.

For unattended installation, explicitly skip the first-run prompts and generate the Web path and credentials automatically:

AIMILIVPN_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/baoweise-bot/aimili-vpngate/main/install.sh)

ml                 # Open the management menu
ml status          # Show status, Web URL, and username
ml logs            # Follow logs
ml restart         # Restart the service
ml password        # Reset Web credentials
ml update          # Update from the stable main branch
ml uninstall       # Uninstall

To inspect the installer first:

git clone --branch main --single-branch https://github.com/baoweise-bot/aimili-vpngate.git
cd aimili-vpngate
sudo bash install.sh

Universal Linux source archives and SHA-256 checksums are available from GitHub Releases. Version changes are documented in the Release Notes.

Option 2: Docker Compose

The Docker host must provide /dev/net/tun, host networking, NET_ADMIN, and NET_RAW.

git clone --branch main --single-branch https://github.com/baoweise-bot/aimili-vpngate.git
cd aimili-vpngate
docker compose pull
docker compose up -d
docker logs -f aimilivpn

Image: ghcr.io/baoweise-bot/aimili-vpngate:2.1

Update:

docker compose pull
docker compose up -d

Show the docker run command

docker run -d \
  --name aimilivpn \
  --restart unless-stopped \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  --device /dev/net/tun:/dev/net/tun \
  -e UI_HOST=0.0.0.0 \
  -e UI_PORT=8787 \
  -e LOCAL_PROXY_HOST=127.0.0.1 \
  -e LOCAL_PROXY_PORT=7928 \
  -v aimilivpn-data:/data \
  ghcr.io/baoweise-bot/aimili-vpngate:2.1

Build locally when GHCR is unavailable

git clone --branch main --single-branch https://github.com/baoweise-bot/aimili-vpngate.git
cd aimili-vpngate
docker compose build
docker compose up -d

Connection and Use

1. Sign in to the Web dashboard

For a source installation, open the URL printed by the installer:

http://VPS_IP:8787/private_path/

Run ml status to recover the URL, or ml password to reset credentials.

Docker users can read the initial Web configuration with:

docker exec aimilivpn cat /data/ui_auth.json

Use its secret_path, username, and password, then change them after the first sign-in.

2. Fetch and connect to a node

1. Sign in and wait for the first node list, or select Update nodes.
2. Filter by country and use Test to measure reachability and latency from the VPS.
3. Select Switch on the target node. A failed target precheck should leave the current usable connection in place when possible.
4. Choose Smart Auto, Fixed Country, or Fixed IP routing.
5. Confirm the VPN state and outbound IP in the status area.

3. Use the proxy on the VPS

HTTP, HTTPS website proxying, and SOCKS5 share 127.0.0.1:7928. HTTPS sites use the HTTP proxy's CONNECT method, so the proxy URL remains http://127.0.0.1:7928.

# HTTP / HTTPS
curl -x http://127.0.0.1:7928 https://api.ipify.org

# SOCKS5 with remote DNS resolution
curl --proxy socks5h://127.0.0.1:7928 https://api.ipify.org

4. Connect from another computer

The proxy listens on the VPS loopback address by default. Use an SSH tunnel instead of exposing it publicly:

ssh -N \
  -L 8787:127.0.0.1:8787 \
  -L 7928:127.0.0.1:7928 \
  root@VPS_IP

After the tunnel is established:

• Web: http://127.0.0.1:8787/private_path/
• HTTP / HTTPS proxy: 127.0.0.1:7928
• SOCKS5 proxy: 127.0.0.1:7928; enable remote DNS or socks5h when available

Warning

Port 7928 has no public-facing user authentication by default. Never expose it directly without a firewall, source-IP restriction, or another reliable access-control layer.

Website, Community, and Video

Destination	Purpose	Link
Website / forum	Announcements and discussion	339936.xyz
Telegram group	Real-time community chat	t.me/arestemple
YouTube tutorial	Installation and usage video	Watch
GitHub Issues	Reproducible bugs and feature requests	Open an issue
Email	Bug reports and contact	yaohunse7@gmail.com

Scope of Use and Legal Notice

Caution

By downloading, deploying, or using this project, you are responsible for confirming compliance with the laws of your location, the laws where the VPS is hosted, provider terms, and applicable VPNGate rules. This section defines project boundaries, is not legal advice, and cannot guarantee exemption from any liability imposed by law.

1. Permitted purpose: Use only for lawful network research, education, development testing, privacy protection, and authorized access. Do not use it to evade lawfully imposed controls, gain unauthorized access, attack or scan systems, send spam, commit fraud, infringe rights, or conduct any unlawful activity.
2. Network and regional restrictions: Some regions and data centers may restrict VPNGate, GitHub mirrors, or remote VPN nodes. The project does not guarantee continuous availability in any region or on any host. Use it only where local law and provider terms permit.
3. Third-party nodes: VPNGate nodes are operated by third-party volunteers. This project does not own, control, or audit them and cannot guarantee availability, speed, security, privacy practices, or logging behavior. Do not send passwords, financial information, trade secrets, or other sensitive data through untrusted nodes.
4. User responsibility: The user is responsible for node selection, traffic, deployment location, exposed ports, and account security, and bears legal responsibility for unlawful use, misconfiguration, third-party nodes, outages, data leaks, or account abuse.
5. No warranty: The software is provided “as is.” To the maximum extent permitted by applicable law, maintainers disclaim warranties of availability, merchantability, fitness for a particular purpose, and indirect damages. Liability that cannot lawfully be excluded remains unaffected.
6. Stop if uncertain: If you cannot confirm that local law and provider policy permit this use, do not deploy or use the software and consult a qualified lawyer in the relevant jurisdiction.

Stable Release · Issues · GPL-3.0 License