AimiliVPN: a VPNGate node manager and proxy gateway for Linux VPS
aimili-vpngate是一个借助vpngate.net让Linux用干净ip出站的代理工具。
At a glance
- What is it?
- AimiliVPN turns a Linux VPS into a VPNGate exit node with an HTTP, HTTPS and SOCKS5 proxy on one port. It is a single-host tool with a narrow, clearly stated job, and it is not a desktop VPN client.
- Who is it for?
- Adopt AimiliVPN if you control a Linux VPS with TUN/TAP enabled and you want a scriptable HTTP or SOCKS5 exit that you reach through an SSH tunnel. Do not adopt it on Windows, macOS or Docker Desktop, and do not expose 7928 to the public internet, because the README states that port has no user authentication.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem AimiliVPN addresses: a clean exit IP from a VPS you already own
Most VPN tooling is built for a laptop. AimiliVPN is built for a Linux server that needs to make outbound requests from an IP that is not its own. The README describes it as a VPNGate node manager and an HTTP, HTTPS and SOCKS5 proxy gateway for Linux VPS hosts. The unit of work is the node list: the tool fetches VPNGate nodes, tests them, connects the host to one over OpenVPN, and then offers that connection to local processes as a proxy on 127.0.0.1:7928.
The audience is narrow and specific. You need root, a supported Linux distribution (Ubuntu, Debian, Alpine, CentOS, RHEL, Rocky Linux, AlmaLinux, Fedora, Oracle Linux or Amazon Linux), OpenVPN, iptables, policy routing and TUN/TAP. The README states plainly that Windows and macOS can act as proxy clients but cannot run the full gateway, and that Docker Desktop does not equal a Linux VPS with host TUN access. If you want a consumer VPN app, this is the wrong project. If you run a scraper, a scheduled job or an API client on a VPS and want its egress to come from a rotating public node, the shape fits.
How the node manager, OpenVPN and the shared proxy port fit together
The repository layout shows four Python modules at the top level: vpngate_manager.py, vpn_utils.py, proxy_server.py and snapshot_utils.py. The README says the project uses the Python standard library to manage VPNGate nodes, which is consistent with a deployment that installs python3 from the distribution and nothing else. The Dockerfile copies exactly those four files plus a mirror directory, then byte-compiles them at build time with python3 -m py_compile. There is no pip install step in the image.
The data flow is: node list fetched and cached, nodes filtered by country and tested for measured latency, one node selected, OpenVPN brings up a tunnel, and the proxy server binds a single local port that speaks HTTP, HTTPS through CONNECT, and SOCKS5. The README's table gives the two listening surfaces: the web panel on TCP 8787 behind a secret path plus credentials, and the local proxy on 127.0.0.1:7928. A snapshot_utils module suggests node state is written to disk so a restart does not begin from an empty list, though the README does not spell out the snapshot format.
One detail worth noting: switching nodes is not atomic. The README says that when the target node fails pre-checks, the program tries to keep the current working connection. That is a deliberate choice in favour of availability over strict switching, and it means a failed switch can leave you on the old exit IP without an obvious error, unless you check the exit IP yourself.
Installing AimiliVPN on a Linux VPS and taking the first proxy request
The README's quick install is a single command run as root. It must be run on a supported Linux VPS with TUN/TAP enabled in the control panel and /dev/net/tun present.
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. When it finishes, the terminal prints the full web panel address, the random secret path, and the login credentials. If you prefer to review the script first, the README gives a clone-then-run path.
git clone --branch main --single-branch https://github.com/baoweise-bot/aimili-vpngate.git
cd aimili-vpngate
sudo bash install.shDay-to-day control goes through the ml command. The README lists ml status, ml logs, ml restart, ml password, ml update and ml uninstall. ml status is the one you need first, because it prints the web address and account if you lost them.
ml status
ml logsOnce the panel is open, the README's sequence is: wait for the first node load or click update, filter by country, test a node for measured latency, then click switch. After the status area shows the VPN connected, confirm the exit IP from the host itself. The HTTP and HTTPS proxy and the SOCKS5 proxy share port 7928, so both examples below hit the same listener.
curl -x http://127.0.0.1:7928 https://api.ipify.org
curl --proxy socks5h://127.0.0.1:7928 https://api.ipify.orgIf the address that comes back is the node's rather than your VPS's, the tunnel and the proxy are both working. For Docker, the compose file sets DEPLOYMENT_MODE to docker, VPNGATE_DATA_DIR to /data, UI_HOST to 0.0.0.0, UI_PORT to 8787, LOCAL_PROXY_HOST to 127.0.0.1 and LOCAL_PROXY_PORT to 7928, and it requires host networking plus NET_ADMIN, NET_RAW and /dev/net/tun. The Dockerfile exposes 8787/tcp and 7928/tcp and includes a healthcheck that opens a TCP connection to the UI port.
Where AimiliVPN breaks: TUN access, unauthenticated proxy port and node quality
The most concrete limitation is stated in the README itself: port 7928 has no user authentication facing the public internet, and the project warns against opening it without a firewall, source IP restrictions or other access control. The default bind is 127.0.0.1, and the recommended way to reach it from a laptop is an SSH tunnel forwarding both 8787 and 7928. That is a sound default, but it means the tool is not a drop-in remote proxy. Anyone who wants a proxy reachable from arbitrary clients has to add their own authentication layer in front of it.
The second limitation is environmental. The README's network availability note says that regions, data centres and network providers may restrict DNS, the VPNGate API, GitHub mirrors or VPN protocols, and that mirrors and local caching improve node list availability but cannot guarantee a connection on every machine. In other words, the node list can be healthy while the tunnel still fails. That failure mode is invisible from the panel until you test.
The third is node quality. VPNGate nodes are volunteer-run and their throughput, uptime and IP reputation vary. The README offers country filtering, measured latency testing, and smart auto, fixed country or fixed IP modes, which is a reasonable toolkit, but it does not promise a stable exit IP over time. Workloads that depend on a consistent IP (payment flows, sessions tied to an address, allowlists) are a poor fit. So are hosts that cannot enable TUN/TAP, including most container platforms that do not pass /dev/net/tun through, and Docker Desktop on Windows or macOS.
AimiliVPN compared with running OpenVPN directly against a VPNGate config
The obvious alternative is to download a VPNGate .ovpn file and run OpenVPN yourself. That approach gives you the tunnel and nothing else: no node list refresh, no country filter, no latency test, no web panel, no switch action, and no proxy listener. You would write your own iptables and policy routing rules, and you would manage node rotation by hand. AimiliVPN packages exactly that missing layer, which is why the project exists.
A second alternative is a commercial proxy or residential proxy service. The difference is not just price. A paid proxy gives you a contractual exit IP with a known operator, and usually authentication on the endpoint. AimiliVPN gives you a volunteer VPNGate node with no endpoint authentication and no operator guarantee. If your requirement is auditability or a stable geolocation, the paid service is the better tool and AimiliVPN is simply the wrong one. If your requirement is low-cost, self-hosted rotation on a VPS you already pay for, and you can tolerate node churn, the VPNGate route is the cheaper one.
A third alternative is a plain SSH dynamic forward (ssh -D) from the VPS. It gives you a SOCKS5 proxy with SSH's authentication, but the exit IP is the VPS's own, which defeats the purpose if the point is to leave from a different address.
Maintenance, upgrade path and licence position
The repository is not archived, and the last push was on 2026-09-07, so it is close to current. Releases are frequent and small: v2.1.3, v2.1.4 and v2.1.5 all landed on 2026-08-27, with v2.1.5 marked as the current formal release. The README says version changes are recorded in Release Notes, and that the update channel is either the main branch or the latest formal release. Upgrades go through ml update for source installs, or docker compose pull followed by docker compose up -d for containers. The Docker tag in the compose file is pinned to 2.1, a minor line rather than a digest, so pulling will move you within that line.
The runtime dependency list is small and stable: OpenVPN, iptables, iproute2 and python3, all from distribution packages. That keeps upgrade cost low. The larger ongoing cost is operational: VPNGate node quality changes without warning, and the tool's own node list depends on the VPNGate API being reachable from your VPS.
On licensing, the README badge says GPL-3.0 and links to a LICENSE file, while the repository metadata reports NOASSERTION. Those two signals disagree, and the LICENSE file is the one that governs. Read it before you redistribute or embed the code. This is not legal advice; if the distinction matters for your use, have someone qualified read the file.
Editorial conclusion
Adopt AimiliVPN if you control a Linux VPS with TUN/TAP enabled and you want a scriptable HTTP or SOCKS5 exit that you reach through an SSH tunnel. Do not adopt it on Windows, macOS or Docker Desktop, and do not expose 7928 to the public internet, because the README states that port has no user authentication. Before installing, confirm that your VPS provider and local law permit VPN and TUN use, and verify that /dev/net/tun exists on the host.
Frequently asked questions
Is AimiliVPN secure?
The project's own warning is the clearest answer: port 7928 has no user authentication, so it should not be exposed to the public internet without a firewall or source IP restriction. The web panel on TCP 8787 sits behind a random secret path plus account credentials, and the README recommends reaching both ports through an SSH tunnel.
What is the address of a China VPN server in AimiliVPN?
The documentation does not list specific server addresses. It describes filtering the node list by country and testing measured latency in the web panel before switching, so the address is whatever node you select at that moment rather than a fixed endpoint.
Can AimiliVPN run on Windows or macOS?
No. The README states that Windows and macOS can act as proxy clients but cannot run the full gateway, and that Docker Desktop is not equivalent to a Linux VPS with host TUN capability.
Which port does the AimiliVPN proxy listen on?
The local proxy listens on 127.0.0.1:7928 and serves HTTP, HTTPS through CONNECT, and SOCKS5 from that single port. The web management panel uses TCP 8787.
How do I update AimiliVPN?
Source installs update with ml update, which pulls from the main formal branch. Docker deployments update with docker compose pull followed by docker compose up -d.
Community notes