manual-connections: native WireGuard and OpenVPN profiles for Private Internet Access

What the scripts actually are

The repository contains documentation on how to create native WireGuard and OpenVPN connections, and on how to enable port forwarding if you need that feature. The stated design goal is that the scripts were written so that they are easy to read and to modify, with a lot of comments so that the information you might need is in the code, and the invitation at the end of the introduction is to fork the repository and customise the scripts for your setup. The primary language is Shell, and the top level shows the shape of it: a run_setup.sh entry point, separate scripts for connecting over WireGuard and over OpenVPN with a token, scripts for fetching a token, a region and a dedicated IP, a port_forwarding.sh, an openvpn_config directory, and a certificate file. The MIT licence applies and the last push was on 2026-09-23.

The quick test is three commands

The documentation opens with a short version, labelled as the quick test, and it is worth doing before reading anything else:

git clone https://github.com/pia-foss/manual-connections.git
cd manual-connections
sudo ./run_setup.sh

The three steps are clone, change directory and run the setup script with root privileges. Running as root is required because the job includes writing system configuration and bringing up a tunnel. Everything after that is the documentation: dependencies, disclaimers, the confirmed distributions, the third party repositories, port forwarding, the automated setup and the manual port forwarding test. The last point in the table of contents is the manual PF testing section, which is there because port forwarding is the part people usually cannot get from the official client and therefore the part most likely to send someone to this repository in the first place.

Dependencies are four packages and two of them are conditional

The dependency list is short and the conditional entries are the interesting ones, because they tell you which protocol you are committing to. You need curl and jq regardless of protocol. If you are using WireGuard you additionally need wireguard-tools, which is wg-quick and the wireguard kernel module. If you are using OpenVPN you need openvpn. That is the whole list, and it is worth checking before you start, since the setup script will fail partway through if jq is missing, and jq is what the scripts use to read the API responses. The scripts themselves are all bash, and the environment variable style throughout the project is lowercase for the switches, which is a small consistency you notice when you copy a one-liner from the documentation.

The disclaimers are the part to read carefully

There are five disclaimers and they are specific rather than boilerplate. Port forwarding is disabled server side in the United States, which is a provider-side limitation no script can work around. The scripts do not enforce IPv6 or DNS settings, so that you have the freedom to configure your setup the way you want it to work, and the consequence is stated directly: you should have a good understanding of VPN and cybersecurity to configure it properly. For battle-tested security the official PIA app is the recommendation, since it was designed to protect you in all scenarios. The repository is described as really fresh at this moment, so you will probably be one of the first users. And on support, the project says it can not provide official support for all FOSS platforms because there are simply too many, which is why the third party repository list exists. The same point is made about the third party code, whose quality cannot be guaranteed and which should only be used if you understand the risks.

One-liner configuration and the variables behind it

The fully automated connection is triggered with a single command where the environment variables carry the configuration:

sudo VPN_PROTOCOL=wireguard DISABLE_IPV6=yes DIP_TOKEN=no AUTOCONNECT=true PIA_PF=false PIA_DNS=true PIA_USER=p0123456 PIA_PASS=xxxxxxxx ./run_setup.sh

The variables are documented one by one in the readme, and each has a specific job. PIA_USER and PIA_PASS are your account credentials. DIP_TOKEN is a dedicated IP token, which can be purchased in the client control panel, and the example above sets it to no so the setup does not wait for one. PIA_DNS and PIA_PF are true or false switches for the DNS and port forwarding services. PIA_CONNECT is true or false and controls whether to connect after the configuration has been created, which is only effective for the WireGuard protocol and defaults to true. PIA_CONF_PATH is where the WireGuard configuration file is written, used when you only want the file. MAX_LATENCY is a numeric value in seconds. AUTOCONNECT tests for and selects the server with the lowest latency, and it overrides PREFERRED_REGION, which otherwise sets the region ID for a PIA server.

Port forwarding is the feature the official apps do not expose

The PIA port forwarding service, abbreviated PF in the documentation, is what lets you run services on your own devices and expose them to the internet by using the PIA VPN network. The easiest way to set it up is by using a native PIA application, and the documentation here is for the case where you need port forwarding on native clients and cannot get it that way. One constraint is stated plainly and it is the kind that catches people out: this service can be used only after establishing a VPN connection. The repository has a dedicated port_forwarding.sh and a manual PF testing section, and the third party repository table shows that port forwarding is the feature most of the community forks have added, with the scope column listing PF for the Windows, OpenWrt, OPNsense, pfSense, Synology and TrueNAS forks. That column is a good proxy for what people actually wanted from this project.

The confirmed distribution list is dated, and the releases are older

The tested and confirmed list covers Arch, Artix, Fedora 32 and 33, FreeBSD 12.1 with tweaks required, Manjaro, PureOS amber, Raspberry Pi OS from 2020-08-20, and Ubuntu 18.04 and 20.04. Read that list as a record of what was tested rather than a statement of what works, because the versions named are several years old and the release history has barely moved: v2.0.0 in January 2021 with region selection, colours and other improvements, v1.1.0 in November 2020 with readme improvements and bug fixes, and v1.0.0 in October 2020 which added OpenVPN support. The last push on the repository is in September 2026, so the files are being touched, but the project itself is stable in the sense of barely changing, which is a reasonable thing for a set of scripts that talk to a stable API but does mean the confirmed list has aged.

Editorial conclusion

manual-connections suits a Linux or BSD user who wants a PIA connection without installing the vendor's application, and who needs the port forwarding feature, which the official clients do not expose on every platform. It does not suit someone who wants a supported product, and the project itself says the official app is the battle-tested option. Before you run the setup script, read the disclaimers, because the scripts deliberately do not set IPv6 or DNS for you, and check the confirmed distributions list, since the test matrix is a decade old and the last tagged release is from January 2021.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pia-foss/manual-connections on GitHub
4. README
5. Releases