pia-tun

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

An active PIA subscription
Overview
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 in sync.

See the Unraid guide here:
https://github.com/x0lie/pia-tun/blob/main/Unraid/README.md

Not affiliated with Private Internet Access.

pia-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.


Title image

Latest Version Docker Image Size

Docker Pulls GitHub stars

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

MIT License

Acknowledgments

Special thanks to Kevin for getting me into containerization

Built with:

Not affiliated with Private Internet Access

Categories

Download Statistics

67,563
Total Downloads

Related apps

Explore more like this

Explore all

Links

Details

Repository
x0lie/pia-tun
Last Updated2026-11-16
First Seen2026-11-17

Runtime 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

PIA_USERVariable

REQUIRED. Your Private Internet Access username (typically starts with p).

PIA_PASSVariable

REQUIRED. Your Private Internet Access password.

PIA_LOCATIONSVariable

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
LOCAL_NETWORKSVariable

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'.

PS_CLIENTVariable

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).

PS_USERVariable

Username for the PS_CLIENT API. For qBittorrent you can instead enable 'Bypass authentication for clients on localhost' and leave this empty.

PS_PASSVariable

Password for the PS_CLIENT API (see PS_USER note).

LOG_LEVELVariable

Logging verbosity: error, info, debug, trace.

Default
info|error|debug|trace
Value
info
qBittorrent WebUI (example)Porttcp

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
PF_ENABLEDVariable

Enable PIA port forwarding manually. Automatically enabled when PS_CLIENT or PS_SCRIPT is set.

Default
false|true
Value
false
DNSVariable

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_URLVariable

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

PS_SCRIPTVariable

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_DIP_TOKENVariable

PIA Dedicated IP token to connect to your reserved PIA IP. When set, PIA_LOCATIONS is ignored. Leave empty for standard servers.

BOOTSTRAP_DNSVariable

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.

MTUVariable

Max packet size for the WireGuard interface (pia0). Lower it only if you have MTU issues on your link.

Default
1420
Value
1420
WG_BACKENDVariable

WireGuard implementation: 'kernel' (faster) or 'userspace' (wireguard-go). Auto-detected if empty (kernel preferred).

IPT_BACKENDVariable

iptables backend: 'nft' or 'legacy'. Auto-detected if empty. 'legacy' requires NET_RAW (included in Extra Parameters by default).

SOCKS5_ENABLEDVariable

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
SOCKS5_PORTVariable

Internal SOCKS5 proxy listen port. Useful to avoid a clash with a container sharing the pia-tun network.

Default
1080
Value
1080
HTTP_PROXY_ENABLEDVariable

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
HTTP_PROXY_PORTVariable

Internal HTTP proxy listen port. Useful to avoid a clash with a container sharing the pia-tun network.

Default
8888
Value
8888
PROXY_USERVariable

Optional username to require authentication on the SOCKS5/HTTP proxies.

PROXY_PASSVariable

Optional password for proxy authentication.

METRICS_ENABLEDVariable

Serves /health, /ready, /metrics and /metrics?format=json. Disable to turn off /metrics and /metrics?format=json.

Default
true|false
Value
true
METRICS_PORTVariable

Internal port for the metrics/health server. Useful to avoid clash with common port 9090.

Default
9090
Value
9090
INSTANCE_NAMEVariable

Prometheus label to distinguish multiple pia-tun containers. Leave empty if you run only one.

HC_INTERVALVariable

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
HC_FAILURE_WINDOWVariable

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
GET_REAL_IPVariable

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