Privateerr ⚓¶
Privateerr packages the official, unmodified pia-foss/manual-connections scripts into an Alpine container. It generates matching WireGuard configuration and metadata, then can stay running to recover stale Gluetun connections through a standard-library Python supervisor. The shell adapter remains the boundary to PIA's scripts.
Privateerr remains actively maintained. Privateerr is maintained both as a standalone project and as the privateerr service in every VPN-enabled Plundarr preset. Use Plundarr when you want the complete generated Privateerr-to-Gluetun lane, or use the standalone project when you want Privateerr to generate files for another WireGuard deployment.
Important
Privateerr is not a VPN client. Privateerr does not establish or maintain a tunnel. It writes a PIA WireGuard configuration file for Gluetun, WireGuard, or another compatible VPN client.
The two outputs¶
| File | Consumer | Purpose |
|---|---|---|
config/gluetun/wireguard/wg0.conf |
Gluetun or another WireGuard client | Interface, peer, keys, and endpoint generated by PIA's scripts. |
config/gluetun/wireguard/privateerr.env |
Gluetun wrapper and automation | Selected server name, endpoint, region, and port-forwarding support. |
The metadata solves an awkward timing problem. When PIA chooses a WireGuard endpoint, Gluetun needs the matching server name to perform PIA port forwarding. Privateerr discovers that relationship before Gluetun starts and records it in a machine-readable file.
Recovery without another service¶
Automatic recovery is enabled in fresh Plundarr v2.1.0 deployments containing both Privateerr and Gluetun, and in Privateerr's standalone environment example. It applies fresh connection settings through Gluetun's authenticated API while preserving the shared network namespace. Existing custom deployments without the setting retain generation-only behavior.
The repository example includes qBittorrent and the test-only Buccaneerr validator. Buccaneerr intentionally interrupts the demo tunnel to verify recovery; it is not an extra production service. The quick start separates that test example from a lasting deployment.
Images and platforms¶
Published images are available from GHCR and Docker Hub for linux/amd64,
linux/arm64, and linux/arm/v7.
| Channel | GHCR | Docker Hub |
|---|---|---|
| Stable | ghcr.io/scottgigawatt/privateerr:latest |
scottgigawatt/privateerr:latest |
| Preview | ghcr.io/scottgigawatt/privateerr:edge |
scottgigawatt/privateerr:edge |
Stable semantic-version tags are available when you need an exact release.
Use edge only when intentionally testing the newest successful main build.
Trust boundary¶
- PIA's scripts remain visibly upstream and unmodified in a Git submodule.
- The Python supervisor owns validation, recovery timing, and safe publication; Privateerr-owned shell scripts invoke the upstream scripts and create metadata.
- Test and lint tools stay in Buccaneerr. Production Python uses only the standard library.
- The build uses pinned inputs, scans images with Trivy, publishes multi-architecture manifests, and attaches SBOM/provenance information.
wg0.confis secret material even though it is generated rather than typed.
Read the developer documentation View Privateerr on GitHub Use Privateerr with Plundarr