Gluetun: One Docker Container to Rule Your VPN Clients

The Problem: VPN Clients Are a Mess of Scripts and Configs

Running a VPN inside Docker usually means stitching together a client binary, a configuration file, a way to route traffic, and a firewall. You also need to handle DNS, and you often end up with a container that only works for one provider. Gluetun attacks this by being a single thin container that speaks the client protocol for over twenty providers. The README lists AirVPN, Cyberghost, ExpressVPN, Mullvad, NordVPN, ProtonVPN, Surfshark, and many more. The target user is someone running a home server or a stack of containers who wants a single network egress point. If you run a torrent client, a web scraper, or any service that needs a fixed public IP, Gluetun is meant to sit in front of it. The documentation calls it a 'swiss-army-knife-like VPN client', and that is accurate. It is not a VPN server. It is a client that connects out and then shares that connection.

How Gluetun Works: OpenVPN, WireGuard, and a Kill Switch

Gluetun is written in Go and uses either OpenVPN or WireGuard to establish the tunnel. For OpenVPN, it supports all listed providers. For WireGuard, support is partial: some providers work directly, while others require the 'custom provider' path. The container includes a built-in firewall that acts as a kill switch, allowing traffic only to the VPN servers and to LAN devices. This is not a separate script. It is part of the container's startup logic. The firewall is configured based on environment variables you pass. DNS-over-TLS is also baked in, with the option to pick multiple providers for split-horizon DNS. The container runs on Alpine 3.23, which keeps the image at 43.1MB. That size matters when you pull it on a Raspberry Pi or a slow connection. The architecture support includes amd64, ARM 64, ARM 32 v6 and v7, and even ppc64le, so it covers most small devices.

Getting It Running: The Lazy docker-compose Example

The README offers a docker-compose.yml for 'the laziest' setup. It uses the image qmcgaw/gluetun, adds the NET_ADMIN capability, and mounts /dev/net/tun. You must also set environment variables for your VPN provider, though the README cuts off before showing them. The example exposes ports for the built-in HTTP proxy (8888), Shadowsocks (8388 TCP and UDP), and a SOCKS5 proxy. The key detail is the comment: you must uncomment the container_name line to allow external containers to connect. The volume mount /yourpath:/gluetun is where configuration and state live. The actual per-provider instructions live in the gluetun-wiki, which is a separate repository. That split is a bit awkward: the README points you away for the real setup. But the pattern is clear: you define the provider, the server selection, and the credentials via environment variables, and Gluetun handles the connection.

Built-In Proxies: More Than Just a VPN Pipe

Most VPN clients just give you a tunnel. Gluetun also ships with three proxy servers: a SOCKS5 proxy, an HTTP proxy, and a Shadowsocks server. The README notes that SOCKS5 and Shadowsocks tunnel both TCP and UDP. That is useful for applications that need UDP, like DNS or VoIP. The HTTP proxy handles HTTP and HTTPS over TCP. These proxies run inside the same container, so they automatically route traffic through the VPN tunnel. This means you can point a single application at localhost:8888 or localhost:8388 and get VPN-protected traffic without changing the application's network stack. The trade-off is that you are exposing these ports on your host, so you need to manage access. The documentation does not mention authentication for these proxies, so you should not expose them to the public internet.

Where Gluetun Falls Short: WireGuard Coverage and Provider Gaps

The README is honest about WireGuard support. It lists only eight providers that work directly with WireGuard: AirVPN, FastestVPN, Ivpn, Mullvad, NordVPN, ProtonVPN, Surfshark, and Windscribe. For others like Cyberghost or PIA, you fall back to the custom provider, which means you supply your own WireGuard configuration. That is not a one-liner. The custom provider path also supports AmneziaWG, but only there. If your provider is not in the list at all, Gluetun may not work. The README also notes that port forwarding is only implemented for three providers: PIA, PrivateVPN, and ProtonVPN. If you need port forwarding for torrents and your provider is not one of those, you are out of luck. The project is under active development, with a release every few days, which means the configuration surface can shift. You should pin a specific image tag rather than using latest.

Alternatives: The Custom Provider vs. Rolling Your Own

The obvious alternative is to run OpenVPN or WireGuard directly in a container using the provider's official config files. That gives you full control, but you lose the automation: no built-in DNS-over-TLS, no kill switch, no proxy servers. You would have to write iptables rules yourself. Another alternative is a commercial solution like a VPN router firmware, but that is a different deployment model. Within the Gluetun ecosystem, the custom provider is the fallback for unsupported WireGuard setups. The difference is that the custom provider still gives you Gluetun's firewall and DNS features, while a raw WireGuard container gives you nothing but the tunnel. The README also mentions a Kubernetes sidecar pattern, which is a different approach: instead of a standalone container, you inject Gluetun into a pod. That is a more advanced use case and requires understanding Kubernetes networking.

Maintenance and License: What You Are Committing To

Gluetun is MIT licensed, so you can use it in commercial projects without paying, and you can modify it. The project is actively maintained, with releases on a near-daily basis. That is a double-edged sword: you get fixes and new providers, but you also get breaking changes. The README does not provide a migration guide, so you need to read the release notes. The project is also moving from the qdm12 GitHub user to a new organization, passteque, in 2026. The image names stay the same, but the repository URL changes. The README warns that there are scam websites pretending to be official, so you must verify you are pulling from the correct Docker Hub or GHCR registry. The wiki is a separate repository, and the README points there for provider-specific setup. If you maintain a fork, you will need to track the upstream changes, which are frequent.

Editorial conclusion

Adopt Gluetun if you run Docker and want a single container that handles VPN connection, DNS filtering, and proxy exposure for your other containers or LAN devices, without scripting OpenVPN or WireGuard yourself. Skip it if you need a desktop VPN app or if you demand official support for every provider's latest feature, since WireGuard coverage is incomplete and you must verify that your provider is listed. Before deploying, check the wiki for your provider's required environment variables, confirm the image tag you plan to use, and test the kill switch on a non-critical network, because a misconfigured firewall could block all traffic.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes