pia-tun
Docker app from x0lie's Repository
PIA + WireGuard VPN client with automatic port-syncing to qBittorrent, Deluge, or Transmission. Route other containers through the tunnel, and pia-tun keeps their forwarded port…
Requirements
Overview
Route other containers through the tunnel, and pia-tun keeps their forwarded port in sync.
See the Unraid guide here:
https://github.com/x0lie/pia-tun/blob/main/Unraid/README.md
Not affiliated with Private Internet Access.
Readme
View on GitHubpia-tun
A feature-rich and reliable VPN container image for PIA + WireGuard
Features
- Strict killswitch - Zero-leak design with fast engagement (~25ms on amd64)
- WireGuard speed - Tested at greater than 95% of line speed with automatic MSS clamping
- Reliable reconnect - Handles outages gracefully and avoids reconnect churn
- Port forwarding - Manages port acquisition, keepalive, and expiry/refresh
- Port syncing - Automatically syncs port to qBittorrent, Deluge, Transmission, and custom endpoints
- SOCKS5 + HTTP Proxies - Allows other machines and containers to access VPN (optional authentication)
- DoT Support - Encrypt your DNS requests to further anonymize
- Observability -
/health,/ready,/metrics(prometheus), and/metrics?format=json - Smart server selection - Chooses the lowest-latency server from selected location(s), or from all locations
- Minimal host support - Supports WireGuard userspace (wireguard-go) and iptables-legacy auto-fallback
- No manual auth token - Auth token acquired automatically and kept fresh
- Dedicated IP support - Connect to a reserved PIA IP using your dedicated IP token
- Multi-architecture images - amd64, arm64, and armv7
PIA has reversed their position on rotating IPs. You can read more here, but generally no action needed.

Latest Version Docker Image Size
Quick Start
Versions: latest, develop, and semantic (1, 1.0, 1.0.0)
Copy-Paste Examples:
Running on Unraid? See the guide.
Minimal Compose
services:
pia-tun:
image: x0lie/pia-tun:latest
container_name: pia-tun
cap_add:
- NET_ADMIN
cap_drop:
- ALL
secrets:
- pia_user
- pia_pass
secrets:
pia_user:
file: ./secrets/pia_user
pia_pass:
file: ./secrets/pia_pass
Image also available as ghcr.io/x0lie/pia-tun
More Documentation
Support
License
Acknowledgments
Special thanks to Kevin for getting me into containerization
Built with:
- WireGuard - Fast, modern VPN protocol
- Prometheus - Metrics and monitoring
- Alpine Linux - Lightweight container base
Not affiliated with Private Internet Access
Categories
Download Statistics
Related apps
Explore more like this
Explore allLinks
Details
x0lie/pia-tunRuntime arguments
- Network
bridge- Shell
sh- Privileged
- false
- Extra Params
--cap-drop=ALL --cap-add=NET_ADMIN --cap-add=NET_RAW --device=/dev/net/tun:/dev/net/tun
Template configuration
REQUIRED. Your Private Internet Access username (typically starts with p).
REQUIRED. Your Private Internet Access password.
Comma-separated PIA region IDs (e.g. ca_ontario,ca_toronto). pia-tun tests latency and connects to the best one. Leave 'all' to consider every region. Region IDs: https://serverlist.piaservers.net/vpninfo/servers/v6
- Default
- all
- Value
- all
RECOMMENDED. Necessary to access your downstream containers (like qBittorrent) from your LAN. Set CIDR range(s) allowed to bypass the tunnel (e.g. 192.168.1.0/24). Comma-separated, IPv4/IPv6. Use 'all' for all private ranges or 'none' to disable. The attached container network is auto-included unless set to 'none'.
Auto-sync the forwarded port to a torrent client: qbittorrent, transmission, or deluge. Enables PIA port forwarding automatically. Leave empty if unused (use PS_SCRIPT for unsupported clients).
Username for the PS_CLIENT API. For qBittorrent you can instead enable 'Bypass authentication for clients on localhost' and leave this empty.
Password for the PS_CLIENT API (see PS_USER note).
Logging verbosity: error, info, debug, trace.
- Default
- info|error|debug|trace
- Value
- info
Example downstream port: publish the WebUI/ports of any downstream container (--network=container:pia-tun). Remove or change if you are not running qBittorrent behind the VPN.
- Target
- 8080
- Default
- 8080
- Value
- 8080
Enable PIA port forwarding manually. Automatically enabled when PS_CLIENT or PS_SCRIPT is set.
- Default
- false|true
- Value
- false
DNS resolver: 'pia', 'system', DoT (e.g. tls://one.one.one.one,dns.mullvad.net), or Do53 (e.g. 1.1.1.1,8.8.8.8). Avoid 'system' unless you understand your host resolver (DNS leak risk).
- Default
- pia
- Value
- pia
PS_CLIENT API endpoint. Auto-set to http://localhost:{8080 qbittorrent | 9091 transmission | 8112 deluge}. Override only if the client listens on a non-default port, e.g. http://localhost:8081
Path to a custom script run after each port refresh (for clients PS_CLIENT does not support). Also add a Path mapping for the script. See https://github.com/x0lie/pia-tun/blob/main/docs/compose-examples/ps-script.md
PIA Dedicated IP token to connect to your reserved PIA IP. When set, PIA_LOCATIONS is ignored. Leave empty for standard servers.
Do53-only resolver used to bootstrap PIA hostnames. Leave empty for the default (149.112.112.9, 149.112.112.11). Must not overlap with DNS.
Max packet size for the WireGuard interface (pia0). Lower it only if you have MTU issues on your link.
- Default
- 1420
- Value
- 1420
WireGuard implementation: 'kernel' (faster) or 'userspace' (wireguard-go). Auto-detected if empty (kernel preferred).
iptables backend: 'nft' or 'legacy'. Auto-detected if empty. 'legacy' requires NET_RAW (included in Extra Parameters by default).
Enable the SOCKS5 proxy so other machines/containers can use the VPN. If enabled, also add a Port mapping for SOCKS5_PORT (1080).
- Default
- false|true
- Value
- false
Internal SOCKS5 proxy listen port. Useful to avoid a clash with a container sharing the pia-tun network.
- Default
- 1080
- Value
- 1080
Enable the HTTP proxy so other machines/containers can use the VPN. If enabled, also add a Port mapping for HTTP_PROXY_PORT (8888).
- Default
- false|true
- Value
- false
Internal HTTP proxy listen port. Useful to avoid a clash with a container sharing the pia-tun network.
- Default
- 8888
- Value
- 8888
Optional username to require authentication on the SOCKS5/HTTP proxies.
Optional password for proxy authentication.
Serves /health, /ready, /metrics and /metrics?format=json. Disable to turn off /metrics and /metrics?format=json.
- Default
- true|false
- Value
- true
Internal port for the metrics/health server. Useful to avoid clash with common port 9090.
- Default
- 9090
- Value
- 9090
Prometheus label to distinguish multiple pia-tun containers. Leave empty if you run only one.
Health check frequency in seconds (probes 1.1.1.1, 8.8.8.8, 9.9.9.9 through the tunnel). Default is fine for most.
- Default
- 10
- Value
- 10
Seconds of continuously failing health checks before triggering a reconnect. Increase if your ISP drops briefly and triggers reconnects too eagerly.
- Default
- 30
- Value
- 30
Fetch and log your pre-VPN public IP on startup (useful to confirm the tunnel changed it). Set false for a minimal-egress setup.
- Default
- true|false
- Value
- true