---

🦜 Parrot says: Found this useful? Drop a ⭐ an' help another crew find the map.

─── ⛧ ───

💀 Questions or cursed code? Step forward… enter 🔥HADES🔥.

---

Privateerr 🏴‍☠️

Privateerr is a containerized configuration tool for Private Internet Access (PIA). It packages PIA's official, unmodified manual-connection scripts in a small Alpine container and uses them to generate a WireGuard configuration file plus PIA server metadata for automation.

Use Privateerr when you want wg0.conf for Gluetun, WireGuard, or another compatible VPN client—especially when a Docker Compose deployment needs to generate that configuration repeatably.

Important

Privateerr is not a virtual private network (VPN) client. It does not create or maintain a tunnel. It generates wg0.conf for a VPN client such as Gluetun or WireGuard. Its optional supervisor refreshes Gluetun's connection settings; Gluetun still owns the tunnel.

The upstream PIA scripts remain visible as the docker/pia-manual-connections submodule. Privateerr adds repeatable container execution, safe defaults, health reporting, and a small metadata handoff without modifying those scripts.

Understand the data flow 🧭

Privateerr runs before the VPN client and writes two files. Gluetun—a separate VPN client container—uses wg0.conf to establish the tunnel and reads PIA_WG_SERVER_NAME from privateerr.env when PIA port forwarding is enabled. Other Compose services can then share Gluetun's protected network connection.

flowchart TB
  accTitle: Privateerr configuration handoff
  accDescr: Privateerr runs the unmodified PIA scripts and writes a WireGuard configuration plus server metadata. Gluetun uses those files to start the VPN tunnel, and other Compose services share Gluetun's protected network connection.

  PIA["📜 PIA manual-connection scripts"]
  Privateerr["🏴‍☠️ Privateerr generates<br/>PIA WireGuard configuration"]
  Files["📦 wg0.conf + privateerr.env"]
  Gluetun["🛡️ Gluetun starts<br/>the VPN tunnel"]
  Services["🚢 Compose services use<br/>Gluetun networking"]

  PIA -->|"Unmodified scripts"| Privateerr
  Privateerr -->|"Writes configuration and metadata"| Files
  Files -->|"VPN configuration and PIA server name"| Gluetun
  Gluetun -->|"Protected network namespace"| Services

  classDef upstream fill:#fef3c7,stroke:#d97706,color:#451a03,stroke-width:2px
  classDef generation fill:#dbeafe,stroke:#2563eb,color:#172554,stroke-width:2px
  classDef handoff fill:#ede9fe,stroke:#7c3aed,color:#2e1065,stroke-width:2px
  classDef connected fill:#dcfce7,stroke:#16a34a,color:#14532d,stroke-width:2px

  class PIA upstream
  class Privateerr generation
  class Files handoff
  class Gluetun,Services connected

Loading

Generate a WireGuard configuration ⚡

Before you begin, you need an active PIA subscription plus Git, Docker with Docker Compose, and Make. Clone the repository with its PIA submodule, create the private environment file, and edit the PIA values before running Privateerr:

git clone --recurse-submodules https://github.com/scottgigawatt/privateerr.git
cd privateerr
cp example.env .env

The public PIA submodule needs no GitHub SSH key. If cloning reports a submodule error or building reports a missing pia-manual-connections/LICENSE, follow Recover a missing PIA submodule.

Set PIA_USER and PIA_PASS in .env. Keep the file private. The example selects a port-forwarding-capable region with PIA_PF=true. For configuration generation alone, run the command below; it disables recovery and keepalive for that disposable container without changing .env. Stop any running supervisor before generating into its configuration directory.

make run-privateerr

Privateerr writes:

📦 Output	📍 Path	🎯 Used by
🛡️ WireGuard configuration	config/gluetun/wireguard/wg0.conf	Gluetun, WireGuard, or another compatible VPN client
🧭 PIA server metadata	config/gluetun/wireguard/privateerr.env	Compose automation that needs the selected endpoint, region, or port-forwarding details

Warning

Keep live wg0.conf and privateerr.env files private. They can contain VPN connection material and deployment-specific metadata. Run make restore-test-config before committing after a live voyage.

Select a PIA region 🧭

Automatic selection is enabled by default. To pin a region, set PIA_AUTOCONNECT=false and PIA_PREFERRED_REGION=ca in .env. Replace ca with another PIA region ID when needed. See region selection for regeneration steps and recovery behavior.

Recover stale VPN connections ⚓

Privateerr can optionally monitor Gluetun and refresh stale PIA WireGuard settings through Gluetun's authenticated control API. It keeps Gluetun's container running and needs no extra service or Docker socket. The supplied environment example enables recovery by default. Set a private shared API key before starting; image-only deployments that omit the setting retain their existing behavior.

See automatic Gluetun recovery for setup, API authentication, timing, and limitations. Gluetun remains responsible for the VPN tunnel and port forwarding. The example runs Privateerr without privileged mode or Linux capabilities; see container hardening and image-only upgrades.

Start Privateerr with Gluetun 🐳

The repository includes a single docker-compose.yml for Privateerr, Gluetun, qBittorrent, and the Buccaneerr validator. qBittorrent shares Gluetun's VPN namespace and receives its forwarded port. Before starting:

1. Generate a shared recovery API key with openssl rand -hex 24 and set PRIVATEERR_GLUETUN_API_KEY in .env.
2. Review qBittorrent's user/group IDs, storage paths, and Web UI port in .env.
3. Follow the complete qBittorrent example for application access and validation.

Buccaneerr deliberately interrupts the VPN briefly to verify automatic recovery. Start the full test example with:

make up

Use make ps to inspect service status and make logs to read output. For a lasting application deployment without fault injection, start only the three application services as described in the recovery guide.

Find commands and image channels ⚙️

Run make or make help for the command menu. The maintenance reference covers inspection, backups, cleanup, and generated files. Buccaneerr's testing guide explains offline checks and live PIA validation.

Privateerr and Buccaneerr support linux/amd64, linux/arm64, and linux/arm/v7; individual applications can support fewer architectures. Use latest for stable releases, edge to preview successful main builds, or an exact version to select a release. See registry publishing and image channels for tags, registries, and supply-chain controls.

Read more and get help 📚

• Developer documentation: Supervisor architecture, contributor guides, and generated Python reference.
• Advanced usage: Testing, builds, publishing, maintenance, and generated files.
• Configuration directories: Runtime state and Gluetun handoff paths.
• Host scripts: Backup, credential preflight, cleanup, and status helpers.
• Buccaneerr testing: Offline checks and live end-to-end validation.
• Support: Usage questions, bugs, documentation requests, and safe reporting routes.
• Contributing: Development setup and pull request expectations.
• Security policy: Supported versions and private vulnerability reporting.
• Code of Conduct: Community expectations and enforcement.

Privateerr is licensed under the Apache License 2.0. The bundled PIA manual-connection scripts remain under PIA's MIT license.

Fair winds, private keys below deck, and no VPN-client identity crises. 🏴‍☠️