                  internet
                     │
              ┌──────┴──────┐
              │    Host      │
              │  tinyproxy   │  ← PIA API bootstrap proxy
              │  10.100.0.1  │
              └──────┬───────┘
                     │ br-vpn (no IPMasquerade)
        ┌────────────┼──────────────┐
        │            │              │
 ┌──────┴──────┐ ┌───┴────┐  ┌─────┴──────┐
 │ VPN ctr     │ │ servarr│  │transmission│
 │ 10.100.0.2  │ │  .11   │  │   .10      │
 │ piaw (WG)   │ │        │  │            │
 │ gateway+NAT │ └────────┘  └────────────┘
 └─────────────┘

Host creates the WG interface (encrypted UDP stays in host netns) and runs tinyproxy on the bridge so the VPN container can bootstrap PIA auth before WG is up.
VPN container authenticates with PIA via the proxy, configures WG, sets up NAT (masquerade bridge→WG) and optional port forwarding DNAT.
Service containers default-route through the VPN container. No WG interface = no internet if VPN is down = leak-proof by topology.
Host reaches containers directly on the bridge for nginx reverse proxying.

Key design decisions

Bridge, not veth pairs: All containers share one bridge (br-vpn), so the VPN container can act as a single gateway. The host does NOT masquerade bridge traffic — only the VPN container does (through WG).
Port forwarding is implicit: If any container sets receiveForwardedPort, the VPN container automatically handles PIA port forwarding and DNAT. No separate toggle needed.
DNS through WG: Service containers use the VPN container as their DNS server. The VPN container runs systemd-resolved listening on its bridge IP, forwarding queries through the WG tunnel.
Monthly renewal: pia-vpn-setup uses Type=simple + Restart=always + RuntimeMaxSec=30d to periodically re-authenticate with PIA and get a fresh port forwarding signature (signatures expire after ~2 months). Service containers are unaffected during renewal.

Files

File	Purpose
`default.nix`	Options, bridge, tinyproxy, host firewall, WG interface creation, assertions
`vpn-container.nix`	VPN container: PIA auth, WG config, NAT, DNAT, port refresh timer
`service-container.nix`	Generates service containers with static IP and gateway→VPN
`scripts.nix`	Bash function library for PIA API calls and WG configuration
`ca.rsa.4096.crt`	PIA CA certificate for API TLS verification

Usage

pia-vpn = {
  enable = true;
  serverLocation = "swiss";

  containers.my-service = {
    ip = "10.100.0.10";
    mounts."/data".hostPath = "/data";
    config = { services.my-app.enable = true; };

    # Optional: receive PIA's forwarded port (at most one container)
    receiveForwardedPort = { port = 8080; protocol = "both"; };
    onPortForwarded = ''
      echo "PIA assigned port $PORT, forwarding to $TARGET_IP:8080"
    '';
  };
};

Debugging

# Check VPN container status
machinectl shell pia-vpn
systemctl status pia-vpn-setup
journalctl -u pia-vpn-setup

# Verify WG tunnel
wg show

# Check NAT/DNAT rules
iptables -t nat -L -v
iptables -L FORWARD -v

# From a service container — verify VPN routing
curl ifconfig.me

# Port refresh logs
journalctl -u pia-vpn-port-refresh