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.

App container→Shared network→Gluetun tunnel→VPN server→Internet

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

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

Step 3 — verify, then try to break it

  1. Exit IP test: docker exec gluetun wget -qO- https://ifconfig.me should print the VPN server's IP, and the same command inside the attached app must match it — never your home IP.
  2. 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.
  3. 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

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

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.

Related guides