🚀 Docker AdGuard VPN CLI

Multi-architecture AdGuard VPN CLI in Docker containers
Universal compatibility • Automated builds • Production ready

Report Bug · Request Feature

🌟 About The Project

This project provides AdGuard VPN CLI in Docker containers with universal multi-architecture support. Built with automated CI/CD pipelines, it offers seamless VPN connectivity across all major platforms in a containerized environment.

✨ Key Features

• 🏗️ Multi-Architecture Support: Native builds for amd64, arm64, and armv7
• 🤖 Automated Builds: Daily builds tracking latest AdGuard VPN CLI releases
• 🐳 Dual Registry: Available on both Docker Hub and GitHub Container Registry
• 🔒 Kill Switch: Built-in network protection when VPN disconnects
• 🌐 SOCKS5 Proxy: Optional proxy server functionality
• ⚡ Production Ready: Optimized for performance and reliability

🏗️ Built With

• Base: Ubuntu 24.04 LTS for maximum compatibility
• Build System: Docker Buildx with GitHub Actions
• Architecture: Multi-stage builds with optimized caching
• Security: Non-root execution and health checks

(back to top)

🚀 Getting Started

Quick Start (Universal)

One command works on any architecture:

# Pull the latest image (auto-detects your architecture)
docker pull supersunho/adguardvpn-cli:latest

# Run with environment variables
docker run -d \
  --name adguard-vpn \
  --cap-add NET_ADMIN \
  --device /dev/net/tun \
  -e ADGUARD_USERNAME="your_username" \
  -e ADGUARD_PASSWORD="your_password" \
  -e ADGUARD_CONNECTION_LOCATION="US" \
  supersunho/adguardvpn-cli:latest

🐳 Available Images

Docker Hub (Recommended)

# Universal images (auto-detect architecture)
supersunho/adguardvpn-cli:latest                   # Latest version
supersunho/adguardvpn-cli:1.2.37                   # Specific version

# Architecture-specific images
supersunho/adguardvpn-cli:latest-amd64              # Intel/AMD (x86_64)
supersunho/adguardvpn-cli:latest-arm64              # Apple Silicon/ARM64
supersunho/adguardvpn-cli:latest-armv7              # Raspberry Pi/ARMv7

GitHub Container Registry (Alternative)

# Universal images
ghcr.io/supersunho/docker-adguardvpn-cli:latest     # Latest version
ghcr.io/supersunho/docker-adguardvpn-cli:1.2.37     # Specific version

# Architecture-specific images
ghcr.io/supersunho/docker-adguardvpn-cli:latest-amd64
ghcr.io/supersunho/docker-adguardvpn-cli:latest-arm64
ghcr.io/supersunho/docker-adguardvpn-cli:latest-armv7

(back to top)

💡 Usage Examples

AdGuard VPN CLI + qBittorrent

Create a .env file with your credentials (see Environment Variables):

ADGUARD_USERNAME=your_username
ADGUARD_PASSWORD=your_password
ADGUARD_CONNECTION_LOCATION=US
ADGUARD_CONNECTION_TYPE=TUN
ADGUARD_USE_KILL_SWITCH=true

Then use this docker-compose.yml:

version: "3.8"
services:
  adguard-vpn-cli:
    image: supersunho/adguardvpn-cli:latest
  container_name: adguard-vpn-cli
  restart: unless-stopped
  env_file: .env
  cap_add:
    - NET_ADMIN
  devices:
    - /dev/net/tun
  ports:
    - "6089:6089"       # qBittorrent WebUI
    - "6881:6881"       # BitTorrent TCP
    - "6881:6881/udp"   # BitTorrent UDP
  healthcheck:
    test: ["CMD", "ping", "-c", "1", "www.google.com"]
  interval: 60s
  timeout: 10s
  retries: 3

qbittorrent:
  image: linuxserver/qbittorrent:latest
  container_name: qbittorrent
  depends_on:
    - adguard-vpn-cli
  network_mode: service:adguard-vpn-cli
  environment:
    - PUID=1000
    - PGID=1000
    - TZ=Asia/Seoul
  volumes:
    - ./config:/config
    - ./downloads:/downloads
  restart: unless-stopped

Standalone VPN with SOCKS5 Proxy

version: "3.8"
services:
  adguard-vpn:
  image: supersunho/adguardvpn-cli:latest
  container_name: adguard-vpn
  restart: unless-stopped
  cap_add:
    - NET_ADMIN
  devices:
    - /dev/net/tun
  ports:
    - "1080:1080"       # SOCKS5 proxy
  environment:
    - ADGUARD_USERNAME=your_username
    - ADGUARD_PASSWORD=your_password
    - ADGUARD_CONNECTION_LOCATION=JP
    - ADGUARD_CONNECTION_TYPE=SOCKS5
    - ADGUARD_SOCKS5_HOST=0.0.0.0
    - ADGUARD_SOCKS5_PORT=1080
    - ADGUARD_USE_KILL_SWITCH=true

(back to top)

⚙️ Environment Variables

🔐 Authentication (Required)

Variable	Description	Default	Example
ADGUARD_USERNAME	Your AdGuard VPN username	"username"	"john.doe@example.com"
ADGUARD_PASSWORD	Your AdGuard VPN password	"password"	"your_secure_password"

🌍 Connection Settings

Variable	Description	Default	Allowed Values
ADGUARD_CONNECTION_LOCATION	VPN server location	"JP"	See Available Locations
ADGUARD_CONNECTION_TYPE	VPN operating mode	"TUN"	TUN / SOCKS5

🔒 SOCKS5 Proxy Settings

Variable	Description	Default	Notes
ADGUARD_SOCKS5_USERNAME	SOCKS5 proxy username	"username"	Required for non-localhost access
ADGUARD_SOCKS5_PASSWORD	SOCKS5 proxy password	"password"	Required for non-localhost access
ADGUARD_SOCKS5_HOST	SOCKS5 listen address	"127.0.0.1"	Use 0.0.0.0 for external access
ADGUARD_SOCKS5_PORT	SOCKS5 listen port	1080	Any available port

🛡️ Security & Network

Variable	Description	Default	Allowed Values
ADGUARD_USE_KILL_SWITCH	Enable kill switch protection	true	true / false
ADGUARD_USE_KILL_SWITCH_CHECK_INTERVAL	Kill switch check interval (seconds)	30	10 or higher recommended
ADGUARD_SET_SYSTEM_DNS	Set system DNS servers	false	true / false
ADGUARD_USE_CUSTOM_DNS	Use custom DNS servers	true	true / false
ADGUARD_CUSTOM_DNS	Custom DNS server	"1.1.1.1"	Any valid DNS server

📊 Advanced Settings

Variable	Description	Default	Allowed Values
ADGUARD_USE_QUIC	Enable QUIC protocol	true	true / false
ADGUARD_SEND_REPORTS	Send crash reports	false	true / false

Important

SOCKS5 Security: When setting ADGUARD_SOCKS5_HOST to non-localhost addresses (e.g., 0.0.0.0), always protect the proxy with username and password authentication.

Tip

Kill Switch Interval: Very short check intervals (< 10 seconds) can cause unnecessary resource usage. 30 seconds is recommended for most use cases.

(back to top)

🌍 Available Locations

Choose any City, Country, or ISO Code for ADGUARD_CONNECTION_LOCATION:

🗺️ Complete Location List (Click to expand)

ISO	Country	City
🇺🇸 US	United States	Seattle, Silicon Valley, Phoenix, Las Vegas, Denver, Dallas, Los Angeles, Atlanta, New York, Miami, Boston, Chicago
🇩🇪 DE	Germany	Berlin, Frankfurt
🇬🇧 GB	United Kingdom	Manchester, London
🇫🇷 FR	France	Paris, Marseille
🇪🇸 ES	Spain	Barcelona, Madrid
🇮🇹 IT	Italy	Rome, Milan, Palermo
🇨🇦 CA	Canada	Vancouver, Montreal, Toronto
🇯🇵 JP	Japan	Tokyo
🇰🇷 KR	South Korea	Seoul
🇦🇺 AU	Australia	Sydney
🇸🇬 SG	Singapore	Singapore
🇭🇰 HK	Hong Kong	Hong Kong
🇹🇼 TW	Taiwan	Taipei
🇳🇱 NL	Netherlands	Amsterdam
🇨🇭 CH	Switzerland	Zurich
🇦🇹 AT	Austria	Vienna
🇧🇪 BE	Belgium	Brussels
🇩🇰 DK	Denmark	Copenhagen
🇫🇮 FI	Finland	Helsinki
🇳🇴 NO	Norway	Oslo
🇸🇪 SE	Sweden	Stockholm
🇵🇱 PL	Poland	Warsaw
🇨🇿 CZ	Czechia	Prague
🇭🇺 HU	Hungary	Budapest
🇷🇴 RO	Romania	Bucharest
🇧🇬 BG	Bulgaria	Sofia
🇬🇷 GR	Greece	Athens
🇪🇪 EE	Estonia	Tallinn
🇱🇻 LV	Latvia	Riga
🇱🇹 LT	Lithuania	Vilnius
🇱🇺 LU	Luxembourg	Luxembourg
🇮🇪 IE	Ireland	Dublin
🇵🇹 PT	Portugal	Lisbon
🇷🇺 RU	Russia	Moscow
🇺🇦 UA	Ukraine	Kyiv
🇰🇿 KZ	Kazakhstan	Astana
🇲🇩 MD	Moldova	Chișinău
🇷🇸 RS	Serbia	Belgrade
🇭🇷 HR	Croatia	Zagreb
🇸🇰 SK	Slovakia	Bratislava
🇨🇾 CY	Cyprus	Nicosia
🇮🇸 IS	Iceland	Reykjavik
🇹🇷 TR	Turkey	Istanbul
🇮🇱 IL	Israel	Tel Aviv
🇦🇪 AE	UAE	Dubai
🇪🇬 EG	Egypt	Cairo
🇮🇷 IR	Iran	Tehran
🇮🇳 IN	India	Mumbai
🇨🇳 CN	China	Shanghai
🇹🇭 TH	Thailand	Bangkok
🇻🇳 VN	Vietnam	Hanoi
🇵🇭 PH	Philippines	Manila
🇮🇩 ID	Indonesia	Jakarta
🇰🇭 KH	Cambodia	Phnom Penh
🇳🇵 NP	Nepal	Kathmandu
🇳🇿 NZ	New Zealand	Auckland
🇿🇦 ZA	South Africa	Johannesburg
🇳🇬 NG	Nigeria	Lagos
🇧🇷 BR	Brazil	São Paulo
🇦🇷 AR	Argentina	Buenos Aires
🇨🇱 CL	Chile	Santiago
🇨🇴 CO	Colombia	Bogotá
🇵🇪 PE	Peru	Lima
🇲🇽 MX	Mexico	Mexico City

🎯 Quick Examples

ADGUARD_CONNECTION_LOCATION="US"              # Any US server
ADGUARD_CONNECTION_LOCATION="Japan"           # Any Japan server
ADGUARD_CONNECTION_LOCATION="London"          # London specifically
ADGUARD_CONNECTION_LOCATION="Silicon Valley" # Silicon Valley specifically

(back to top)

🏗️ Multi-Architecture Support

This project provides native performance across all major architectures:

🖥️ Supported Platforms

Architecture	Platform Examples	Performance
amd64	Intel/AMD desktops, cloud instances	⚡ Excellent
arm64	Apple Silicon (M1/M2/M3), ARM servers	⚡ Native
armv7	Raspberry Pi 3/4, IoT devices	✅ Optimized

🚀 Architecture Detection

Docker automatically selects the optimal image for your platform:

# Same command works everywhere
docker pull supersunho/adguardvpn-cli:latest

# Results:
# Intel/AMD (x86_64)    → pulls amd64 image
# Apple Silicon (M1/M2) → pulls arm64 image
# Raspberry Pi          → pulls armv7 image

🔧 Manual Architecture Selection

If needed, you can explicitly specify an architecture:

# Intel/AMD optimized
docker pull supersunho/adguardvpn-cli:latest-amd64

# Apple Silicon optimized
docker pull supersunho/adguardvpn-cli:latest-arm64

# Raspberry Pi optimized
docker pull supersunho/adguardvpn-cli:latest-armv7

(back to top)

🤖 Automated Builds

📅 Build Schedule

• Daily Builds: Automatically track latest AdGuard VPN CLI releases
• Manual Triggers: On-demand builds via GitHub Actions
• Multi-Registry: Simultaneous publishing to Docker Hub and GHCR

🔍 Build Verification

Every build includes comprehensive testing:

• ✅ Binary verification across all architectures
• ✅ Version compatibility checks
• ✅ Container health validation
• ✅ Multi-platform manifest creation

📊 Build Status

Check the latest build status: GitHub Actions

(back to top)

🔧 Troubleshooting

Common Issues

VPN connection fails

1. Check credentials: Ensure ADGUARD_USERNAME and ADGUARD_PASSWORD are correct
2. Verify location: Use a valid location from the Available Locations list
3. Check permissions: Container needs NET_ADMIN capability and /dev/net/tun access

docker logs adguard-vpn-cli

Kill switch not working

1. Enable kill switch: Set ADGUARD_USE_KILL_SWITCH=true
2. Check interval: Ensure ADGUARD_USE_KILL_SWITCH_CHECK_INTERVAL is reasonable (≥10 seconds)
3. Network configuration: Verify TUN interface is available

SOCKS5 proxy not accessible

1. Host binding: Set ADGUARD_SOCKS5_HOST=0.0.0.0 for external access
2. Authentication: Configure ADGUARD_SOCKS5_USERNAME and ADGUARD_SOCKS5_PASSWORD
3. Port mapping: Ensure Docker port mapping matches ADGUARD_SOCKS5_PORT

🩺 Health Checking

# Check container health
docker inspect adguard-vpn-cli --format='{{.State.Health.Status}}'

# View detailed logs
docker logs --follow adguard-vpn-cli

# Test VPN connectivity
docker exec adguard-vpn-cli curl -s ipinfo.io/ip

(back to top)

🤝 Contributing

Contributions make the open source community amazing! Any contributions are greatly appreciated.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🐛 Reporting Issues

Found a bug? Please check existing issues first, then create a new one with:

• Environment details (OS, Docker version, architecture)
• Steps to reproduce
• Expected vs actual behavior
• Relevant logs

(back to top)

🙏 Acknowledgments

• AdGuard Team - Original AdGuard VPN CLI

(back to top)