AI-VPN that makes your traffic invisible to deep packet inspection
AI-VPN that makes your traffic invisible to deep packet inspection
AIVPN is a UDP-based VPN system that combines standard tunnel encryption with traffic mimicry: outbound packets are reshaped to resemble known application protocols (WebRTC, QUIC, DNS-over-UDP), making the connection statistically indistinguishable from regular application traffic to passive observers.
Key technical properties:
DashMap.…| Module | Location | Purpose |
|---|---|---|
crypto.rs |
aivpn-common |
X25519 key exchange, ChaCha20-Poly1305 AEAD, BLAKE3/HMAC, resonance tag generation |
protocol.rs |
aivpn-common |
Wire format: [8-byte tag][pad_len][inner_header][encrypted payload][poly1305 tag] |
mask.rs |
aivpn-common |
MaskProfile — traffic shaping: header templates, FSM states, IAT distributions |
gateway.rs |
aivpn-server |
Central event loop: UDP receive, session dispatch, NAT forwarding, neural checks |
session.rs |
aivpn-server |
SessionManager — DashMap-based O(1) tag lookup, 256-entry replay window, 500-session cap |
neural.rs |
aivpn-server |
Neural Resonance: per-mask MLP 64→128→64, MSE threshold 0.35, auto mask rotation |
client.rs |
aivpn-client |
State machine: Unprovisioned → Connecting → Connected, key exchange, reconnection |
tunnel.rs |
aivpn-client |
Cross-platform TUN: /dev/net/tun (Linux), utun (macOS), Wintun (Windows) |
mimicry.rs |
aivpn-client |
MimicryEngine — applies MaskProfile to outbound packets |
Server-to-server client database synchronization uses ControlPayload::PoolSync carried inside ordinary VPN UDP packets — indistinguishable from client traffic. No separate TCP port or firewall rule required.
| Platform | Server | Client | GUI | TUN driver |
|---|---|---|---|---|
| Linux CLI | ✅ | ✅ | — | /dev/net/tun |
| Linux GUI | — | ✅ | ✅ iced AppImage + tray | /dev/net/tun |
| macOS | — | ✅ | ✅ menu bar | utun |
| Windows | — | ✅ | ✅ egui GUI | Wintun |
| Android | — | ✅ | ✅ native Kotlin | VpnService API |
| iOS | — | ✅ | ✅ SwiftUI | NetworkExtension |
| MikroTik RouterOS 7.6+ | — | ✅ | — | container veth + TUN |
| Entware routers (ARMv7 / MIPSel) | — | ✅ | — | musl static binary |
| Feature | Linux CLI | Linux GUI | Win | Mac | Android | iOS |
|---|---|---|---|---|---|---|
| Traffic Mimicry | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Adaptive Mode (4 levels) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Live Quality Score | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Split Tunnel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| DNS Proxy | ✅ | ✅ | ✅ | ✅ | N/A* | ❌ |
| Kill Switch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| mTLS Certificate | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| FEC (forward error correction) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Traffic Recording | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Device Key / JIT | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| SOCKS5 Proxy | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Full Tunnel | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Diagnostics / Benchmark | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Bootstrap Descriptor Discovery | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Polymorphic Masks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Crowdsourced Mask Feedback (opt-in) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| In-App Admin (roles, client mgmt, revoke, audit)‡ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Pool Topology View + Per-Client Exit Node | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| SSH Server Install Wizard§ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Live Metrics Graphs† | — | — | — | — | — | — |
* Android's VpnService API routes all device traffic (including DNS) through the encrypted tunnel by design — there's no separate local DNS-proxy listener because none is needed; DNS leaks aren't possible on this platform.
† Live Metrics Graphs is a server + Web Management Panel feature, not a client capability — it requires building the server with --features metrics and is viewed from the web dashboard, not from any of the clients above.
‡ See In-App Client Administration & Roles. On desktop, the CLI exposes the same surface via aivpn-client mgmt/aivpn-client role (bridged over the local admin socket); Linux CLI's checkmark reflects that CLI bridge rather than a graphical admin screen.
§ See SSH Server Installer. Requires the client to be built with the ssh-install Cargo feature (bundled by default in the released GUI/mobile builds); on Linux CLI it is the aivpn-client ssh-install {script,probe,run} subcommand rather than a graphical wizard.
platforms/aivpn-web/ provides a full-stack web UI for managing the aivpn server.
Stack: Hono 4 + Bun (backend) · SvelteKit 2 + Svelte 5 + TailwindCSS 4 (frontend) · Layerchart charts · SQLite (default) or PostgreSQL
Features:
admin (full access) and viewer (read-only) — these are the web panel's own login roles, independent of a VPN client's ClientRole. viewer is enforced through a fail-closed allowlist of GET-only proxied endpoints (clients, pool nodes/links/health, masks, status, kernel, events); config, backup, bootstrap export, and mask upload/delete stay admin-only./api/v1/* proxied to the aivpn Unix socket (/run/aivpn/api.sock)/web/events/web/events SSE stream from an in-memory ~10-minute ring buffer (no new persistent storage). Requires the server to be built with --features metrics (see Optional features (Cargo)); the dashboard shows a hint instead of the charts if the server lacks that feature.Quick Start:
# 1. Generate secrets
JWT_SECRET=$(openssl rand -base64 48)
TOTP_KEY=$(openssl rand -base64 32)
# 2. Run with Docker (simplest)
docker run -d --name aivpn-web \
-v /run/aivpn:/run/aivpn \
-e JWT_SECRET="$JWT_SECRET" \
-e TOTP_ENCRYPTION_KEY="$TOTP_KEY" \
-e ORIGIN=https://vpn.example.com \
-p 8080:8080 \
ghcr.io/infosave2007/aivpn-web:latest
# 3. Get the one-time admin password from the startup log
docker logs aivpn-web 2>&1 | grep -A4 "FIRST-TIME SETUP"
# 4. Open https://vpn.example.com and log in with username "admin"Or via docker compose up -d aivpn-web (secrets go in platforms/aivpn-web/.env).
Run (Bun, from source):
cd platforms/aivpn-web
cp .env.example .env # fill JWT_SECRET, TOTP_ENCRYPTION_KEY, ORIGIN
bun install && bun run build
bun run start # listens on PORT (default 8080)Key environment variables:
| Variable | Default | Description |
|---|---|---|
DATABASE_URL |
file:./data/aivpn-web.db |
SQLite path or postgres://... |
JWT_SECRET |
— | Long random string for token signing |
TOTP_ENCRYPTION_KEY |
— | 32-byte base64 key (openssl rand -base64 32) |
ORIGIN |
— | Public HTTPS URL (required for WebAuthn / CSRF) |
UNIX_SOCK |
/run/aivpn/api.sock |
Path to aivpn management socket |
PORT |
8080 |
HTTP listen port |
Makefile targets:
make web # install deps + build frontend
make web-docker # build Docker image aivpn-web:latest
make web-dev # start dev servers (hot reload)An nginx reverse-proxy example is in deploy/nginx/aivpn-web.conf.
Default credentials (first run):
On first startup with an empty database, a random admin password is generated and printed once to the server console:
╔══════════════════════════════════════════════════╗
║ FIRST-TIME SETUP — SAVE THESE NOW ║
╠══════════════════════════════════════════════════╣
║ Username : admin ║
║ Password : ║
╚══════════════════════════════════════════════════╝Save this password immediately — it is shown once only. After logging in, change it in Settings → Security or register a passkey.
OIDC / SSO (optional):
| Variable | Description |
|---|---|
OIDC_ISSUER |
IdP base URL (e.g. https://accounts.google.com) |
OIDC_CLIENT_ID |
OAuth2 client ID |
OIDC_CLIENT_SECRET |
Client secret (omit for public PKCE clients) |
OIDC_MODE |
disabled (default) · enabled (adds SSO button) · exclusive (SSO only) |
OIDC_ROLE_CLAIM |
ID token claim containing the user's role (e.g. role) |
OIDC_ADMIN_VALUE |
Claim value that grants admin role (default: admin) |
The role from OIDC is applied only on first SSO login; admins can override it afterwards in the web panel.
mkdir -p config
docker compose up -d aivpn-serverThe container auto-generates server.key and server.json on first start. It runs with network_mode: host and mounts ./config → /etc/aivpn.
Open UDP port 443 in your firewall:
# UFW
sudo ufw allow 443/udp
# firewalld
sudo firewall-cmd --add-port=443/udp --permanent && sudo firewall-cmd --reloadsudo mkdir -p /etc/aivpn
openssl rand 32 | sudo tee /etc/aivpn/server.key > /dev/null
sudo chmod 600 /etc/aivpn/server.key
sudo ./aivpn-server --listen 0.0.0.0:443 --key-file /etc/aivpn/server.keyThe server automatically enables IPv4 forwarding and installs NAT masquerade rules (nftables preferred, iptables fallback). No manual firewall configuration is required for the tunnel itself.
# Docker
docker compose exec aivpn-server aivpn-server \
--add-client "Alice Phone" \
--key-file /etc/aivpn/server.key \
--clients-db /etc/aivpn/clients.json \
--server-ip YOUR_PUBLIC_IP:443
# Bare metal
aivpn-server \
--add-client "Alice Phone" \
--key-file /etc/aivpn/server.key \
--clients-db /etc/aivpn/clients.json \
--server-ip YOUR_PUBLIC_IP:443Output includes the connection key (aivpn://…) — distribute it to the client.
Add --role viewer|admin to grant that client in-app management access (requires the client to already be device-bound — combine with --device-pubkey to create a device-bound admin in one shot, no separate en
No open issues yet, or sync has not completed.