If you want selected ZimaOS applications to send their traffic through a commercial VPN, the community thread points to Gluetun rather than treating the WireGuard App Store entry as a simple upload-your-client-config interface. The original author initially asked how to run WireGuard as a client, then found Gluetun in ZimaOS and documented the Docker-network approach.
The key design is that the target app shares Gluetun's network namespace. Gluetun owns the VPN tunnel, firewall, and published ports; qBittorrent or another application then uses that network stack instead of its own normal bridge interface.
WireGuard and Tailscale in the ZimaOS App Store Are Not the Same as a VPN Provider Client
Zima-Giorgio replied that WireGuard and Tailscale were available in the App Store. The author then clarified the missing piece: they wanted a client workflow where a provider configuration could be imported and used to route application traffic.
That distinction matters. Tailscale and a self-hosted WireGuard endpoint are useful for private remote-access networking, while Gluetun is designed specifically to connect Docker workloads through supported commercial VPN providers using OpenVPN or WireGuard.
The Source Thread's Gluetun Discovery
The author later wrote that ZimaOS included Gluetun even though searching the App Store for the generic term “VPN” did not make it obvious.
The source advice was to change the tunneled application's networking from normal bridge mode to Gluetun's network namespace and remove the application's own published ports because Gluetun should publish them instead.
network_mode: container:gluetunThat syntax is valid when an external container joins an already running Gluetun container by name.
service:gluetun vs container:gluetun
Current Gluetun documentation distinguishes two common Compose cases:
# Same Compose project
network_mode: "service:gluetun"and:
# Separate Compose project / external container
network_mode: "container:gluetun"Both forms appeared conceptually in the community discussion. The correct one depends on whether Gluetun and the routed application live in the same Compose stack.
Current Gluetun container networking guide
Why qBittorrent Can Still Leak the ISP IP
A later user reported that Gluetun itself showed a NordVPN IP in its logs, but qBittorrent still appeared to use the ISP address when tested. That symptom means “Gluetun is connected” and “qBittorrent is actually sharing Gluetun's network stack” must be tested separately.
Check the qBittorrent container definition and confirm its network mode is really attached to Gluetun. A normal bridge interface alongside Gluetun can leave qBittorrent using the ordinary host route.
Move qBittorrent Ports to the Gluetun Container
Gluetun's current documentation says that when another container shares its network stack, the target application's ports should be published on Gluetun.
For example, if qBittorrent listens internally on port 8080:
services:
gluetun:
image: qmcgaw/gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
ports:
- "8080:8080"
qbittorrent:
image: your-qbittorrent-image
network_mode: "service:gluetun"Do not publish the same qBittorrent port on both containers. That creates the port conflicts described in the source thread.
The Video Referenced in the Community Thread
A later participant explicitly said they followed DB Tech's CasaOS video while trying to route qBittorrent through Gluetun. Because that video is part of the source thread's troubleshooting path, it is preserved here.
The video predates the ZimaOS thread and uses CasaOS, so use it to understand the Docker/Gluetun architecture rather than copying every UI step literally.
A Later User Confirmed a Custom Compose Stack Worked
In November 2025, another community member said the reliable solution was to deploy qBittorrent and Gluetun together as a custom app/Compose stack and configure the VPN provider there. They reported that accessing qBittorrent on their chosen host port then showed VPN-routed traffic.
The source thread links a user-created Gist for that setup. Treat third-party Compose files as examples: review environment variables, image versions, secrets, and network settings before deploying them.
Gluetun Provides a VPN Kill Switch
Current Gluetun documentation describes its firewall as a kill switch: when the VPN path is unavailable, the firewall blocks traffic that should not leave through the normal interface. This is one reason sharing Gluetun's network stack is preferable to simply starting a VPN container beside qBittorrent.
Do not disable Gluetun firewall rules just to make a port reachable. Fix the intended LAN/output routes instead.
Allow LAN Access Deliberately
If the routed app needs to reach local subnets, Gluetun supports FIREWALL_OUTBOUND_SUBNETS. For example:
FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24Use your actual LAN subnet and avoid overlapping it with the VPN tunnel range.
VPN Provider Port Forwarding Is Different from Docker Port Mapping
Gluetun's documentation separates:
- Docker port publishing: making qBittorrent WebUI reachable on your LAN.
- VPN-provider port forwarding: obtaining an inbound port from a VPN provider that supports it.
Do not enable VPN_PORT_FORWARDING just to fix local qBittorrent WebUI access. They solve different problems.
ZimaOS Gluetun Checklist
- Configure Gluetun for your actual VPN provider using the current provider documentation.
- Confirm Gluetun logs show the expected VPN exit IP.
- Put the target app in Gluetun's network namespace.
- Use
service:gluetunfor the same Compose stack orcontainer:gluetunfor an external container. - Remove duplicate published ports from the routed application.
- Publish required WebUI/listening ports on Gluetun.
- Restart the stack.
- Test the target application's public IP independently of Gluetun's own log.
- Keep VPN credentials and WireGuard private keys out of public Compose files.
ZimaOS VPN Client FAQ
Can ZimaOS route only qBittorrent through a VPN?
Yes. The community thread used Gluetun specifically to share its VPN network stack with selected Docker applications instead of tunneling every ZimaOS service.
Why did Gluetun show the VPN IP while qBittorrent still showed the ISP IP?
Because the VPN container can be healthy while qBittorrent is still attached to its normal network. Verify qBittorrent's actual network mode.
Why does changing ports break the qBittorrent WebUI?
When qBittorrent shares Gluetun's network namespace, publish the WebUI port on Gluetun rather than publishing the same port on qBittorrent.
Should I use service:gluetun or container:gluetun?
Use service:gluetun when both services are in the same Compose project. Use container:gluetun when an external container joins a named Gluetun container.
