Gluetun: route any Docker container through a VPN
Some containers should use your normal internet connection, and a few — download clients are the classic case — should only ever speak to the world through a VPN, and stop speaking entirely if the VPN drops. Gluetun is a small container that holds the VPN tunnel open and lets other containers borrow its network. Their traffic exits through the VPN; if the tunnel dies, the kill switch means their traffic exits nowhere. Here is the complete setup.
Published Nov 17, 2026
How it works
Gluetun connects to a commercial VPN provider (it supports dozens, over WireGuard or OpenVPN) and owns a network namespace. Any container started with network_mode: service:gluetun shares that namespace — no network of its own, just Gluetun's tunnel, Gluetun's firewall, and Gluetun's DNS. Two consequences follow: the attached container cannot publish its own ports (Gluetun publishes them on its behalf), and there is no path to the internet except through the tunnel. That second point is the kill switch, and it is architectural, not a setting that can be misconfigured off.
Step 1 — the Gluetun container
services:
gluetun:
image: qmcgaw/gluetun:latest
container_name: gluetun
restart: unless-stopped
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
ports:
- "8080:8080" # web UI of the attached app (step 2)
environment:
- VPN_SERVICE_PROVIDER=mullvad
- VPN_TYPE=wireguard
- WIREGUARD_PRIVATE_KEY=your_key_from_your_provider
- WIREGUARD_ADDRESSES=10.x.x.x/32
- SERVER_COUNTRIES=Netherlands
- FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24 # let attached apps see your LAN
- TZ=America/New_York
- Swap the provider block for yours — Gluetun's wiki documents every provider's variables. WireGuard is faster and simpler wherever the provider offers it.
FIREWALL_OUTBOUND_SUBNETSmatters more than it looks: without it, attached containers cannot reach your LAN, which breaks things like a download client writing to a NAS share on another box or talking to the rest of your stack.- Credentials live in the Compose file here for readability — on a real system, move them into an
.envfile next to the Compose file and out of any git history.
Step 2 — attach a container to the tunnel
Any container joins by giving up its own network. Using a download client as the example:
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
container_name: qbittorrent
restart: unless-stopped
network_mode: "service:gluetun"
depends_on:
gluetun:
condition: service_healthy
environment:
- WEBUI_PORT=8080
- TZ=America/New_York
volumes:
- ./qbittorrent/config:/config
- /path/to/downloads:/downloads
- No
ports:on the attached container — it cannot have any. Its 8080 is published on Gluetun (already done in step 1). depends_onwithservice_healthymakes the app wait until the tunnel is actually up before starting — Gluetun ships a healthcheck for exactly this.- Attached containers reach each other at
localhost(same namespace), and reach the rest of your stack by LAN IP, thanks to the outbound-subnets rule.
Step 3 — verify, then try to break it
- Exit IP test:
docker exec gluetun wget -qO- https://ifconfig.meshould print the VPN server's IP, and the same command inside the attached app must match it — never your home IP. - Kill-switch test: stop the gluetun container's tunnel (or pause the container) and repeat the test from the attached app: the command should fail entirely. Silence is success — a leaked home IP is failure.
- DNS check: attached apps resolve through Gluetun's encrypted DNS by default, so your ISP sees neither the queries nor the traffic.
Port forwarding: if your use case needs an open inbound port through the VPN (some private trackers, for instance), only some providers offer it — Gluetun exposes it as VPN_PORT_FORWARDING=on for the providers that do. Most people never need it; do not chase it speculatively.
Troubleshooting
- Attached app's web UI unreachable: its port is not published on Gluetun, or the LAN subnet rule is missing so return traffic cannot reach you. Check those two first; they cover most cases.
- Gluetun loops 'connecting': bad credentials or the provider's WireGuard key needs regenerating in their portal. The log names the failure stage plainly.
- App cannot see the NAS/LAN:
FIREWALL_OUTBOUND_SUBNETSmust match your actual LAN range — a 10.x or 192.168.0.x house needs its own value, not the example's. - Recreating gluetun strands the apps: containers sharing a network namespace must be recreated after Gluetun is. Compose handles this if the whole stack is brought up together.
Designing the split: what stays outside the tunnel
The mature version of this setup is a deliberate split, not a maximal one. Behind Gluetun: the download clients and anything whose traffic you specifically want the VPN to carry. Outside: Jellyfin and Plex (their remote users and local players expect your real connection, and transcoding traffic gains nothing from a detour), Home Assistant (local discovery and integrations assume a normal LAN citizen), and your monitoring stack (it should report the network as it actually is). This split is also a reliability choice — when the VPN provider has a bad night, exactly one corner of your stack goes quiet, and it is the corner designed to. Resist the urge to route everything 'for privacy': a tunnel around your whole homelab mostly buys you broken discovery, confused geolocation, and debugging sessions you did not need.
Official documentation and references
- Gluetun on GitHub — official repository
- Gluetun Wiki — setup guides and provider configuration
- Gluetun Wiki — setup instructions and environment variables
Frequently asked questions
Is Gluetun a VPN service itself?
No — Gluetun is the client plumbing. You still need an account with a VPN provider (Mullvad, Proton, PIA, Nord and dozens more are supported); Gluetun connects to it and shares the tunnel with your containers.
Which containers should go behind Gluetun?
Only the ones with a reason: download clients are the classic case. Keep media servers, Home Assistant and your everyday stack on the normal connection — routing them through a VPN adds latency and breaks local discovery for no benefit.
Gluetun vs Tailscale — aren't they the same job?
Different jobs. Gluetun pushes container traffic OUT through a commercial VPN for privacy from your ISP and the destination. Tailscale connects YOUR devices together (and can route your phone through home). Many homelabs run both, for different traffic.

