---
title: Gluetun
description: VPN client in a Docker container
showHero: false
author: wompmacho
date: '2026-04-27'
lastmod: '2026-04-27'
tags: ['vpn', 'gluetun', 'networking', 'self-hosted']
---

## What is Gluetun?

`Gluetun` is a lightweight Swiss-army-knife Docker container to connect to VPN servers. I use it as a central VPN gateway for other containers like qBittorrent and Nicotine. By routing other containers through Gluetun, they share its VPN connection and benefit from its killswitch, ensuring no traffic leaks if the VPN drops.

## Docker Compose Example

```yaml
{{% include "/srv/configs/docker_compose/gluetun/docker-compose.yaml" %}}
```

## Utilizing Ports in Docker Compose

When using Gluetun as a network stack for other containers (via `network_mode: "container:gluetun"`), all port mappings must be defined in the **Gluetun service itself**, not in the service being routed.

### Why define ports in Gluetun?
Containers sharing Gluetun's network namespace effectively share its "localhost." Since the routed container has no network stack of its own, Docker cannot map ports directly to it. Gluetun must listen on those ports and pass the traffic through to the shared network namespace.

### How to add a new port:
1.  **Define the mapping in Gluetun**: Add the desired port to the `ports` section of the `gluetun` service.
    ```yaml
    services:
      gluetun:
        ports:
          - '8080:8080' # Example: Web UI for a routed app
    ```
2.  **Use Variables**: It is recommended to use variables in a `.env` file for cleaner management, as seen in my setup:
    ```yaml
    ports:
      - '${TORRENT_WEBUI_PORT}'
    ```
3.  **No ports in routed containers**: Ensure the container using `network_mode: "container:gluetun"` does **not** have a `ports` section, as it will cause an error or be ignored.

### Local Network Access (Firewall)
By default, Gluetun's killswitch might block access to the container's Web UI from your local network. To fix this, you must define your local subnet in the environment:

```yaml
environment:
  - FIREWALL_OUTBOUND_SUBNETS=10.0.0.0/24 # Adjust to match your LAN
```

This allows traffic from your local network to bypass the VPN tunnel, enabling you to access Web interfaces (like qBittorrent) while the VPN is active.

## Routing other containers
To route a container through Gluetun, add the following to its `docker-compose.yaml`:

```yaml
services:
  my-app:
    network_mode: "container:gluetun"
```
