Gluetun — Lightweight VPN Client Container

Introduction

Gluetun is a lightweight Alpine-based Docker container that establishes a VPN tunnel using OpenVPN or WireGuard and exposes an HTTP and Shadowsocks proxy. It supports 30+ VPN providers out of the box and is designed to be the network gateway for other containers using Docker's network sharing.

What Gluetun Does

• Connects to VPN providers via OpenVPN or WireGuard protocols automatically
• Supports 30+ commercial VPN providers with built-in server lists
• Acts as a network gateway so other containers can route traffic through the VPN
• Exposes HTTP proxy on port 8888 and Shadowsocks on port 8388
• Includes a built-in DNS over TLS client and firewall with kill switch

Architecture Overview

Gluetun runs as a minimal Alpine Linux container with iptables-based firewall rules that enforce a kill switch. It manages VPN connections using either the native WireGuard kernel module or OpenVPN client. DNS queries are forwarded through DNS over TLS to prevent leaks. A lightweight Go-based control server exposes a REST API for health checks and dynamic configuration.

Self-Hosting & Configuration

• Set VPN_SERVICE_PROVIDER and credentials via environment variables
• Choose VPN_TYPE as wireguard or openvpn depending on provider support
• Filter servers by country, city, or hostname using SERVER_ variables
• Route other containers through Gluetun with --network=container:gluetun
• Mount /gluetun volume for persistent server lists and custom OpenVPN configs

Key Features

• Kill switch via iptables ensures no traffic leaks if the VPN drops
• DNS over TLS prevents DNS leak with configurable upstream providers
• Built-in HTTP and Shadowsocks proxy for non-Docker clients
• REST API for health checks, public IP queries, and port forwarding
• Automatic server list updates and reconnection on failure

Comparison with Similar Tools

• VPN client on host — Affects all traffic; Gluetun isolates VPN to specific containers only
• WireGuard container — Manual config required; Gluetun automates provider-specific setup
• Hotio qBittorrent-VPN — App-specific; Gluetun is provider-agnostic and app-independent
• Tailscale — Mesh VPN for your devices; Gluetun routes through commercial VPN providers
• Mullvad app — Desktop-only client; Gluetun runs headless in Docker for server use

FAQ

Q: Which VPN providers are supported? A: Over 30 providers including Mullvad, NordVPN, Surfshark, PIA, ProtonVPN, Windscribe, and many more.

Q: Can I use a custom OpenVPN config? A: Yes. Mount your .ovpn file to /gluetun and set VPN_SERVICE_PROVIDER=custom with the appropriate variables.

Q: How do I route another container through Gluetun? A: Use --network=container:gluetun when starting the other container. Its traffic will flow through the VPN tunnel.

Q: Does it support port forwarding? A: Yes, for providers that offer it. Gluetun can request forwarded ports and exposes them via its REST API.

Sources

• https://github.com/qdm12/gluetun
• https://github.com/qdm12/gluetun-wiki