PIA macOS Split Tunnel Watcher

This repository packages a small utility that keeps an eye on Private Internet Access split tunneling on macOS. The check_pia_split.sh script reads the official PIA settings file, tracks the previous state in a per user file, and fires a macOS notification if split tunneling ever drifts into the off state. The installer and uninstaller scripts wrap the entire workflow so you can drop the watcher onto a fresh machine or remove it without hunting through system folders.

What you need first

1. macOS with the standard PIA desktop client installed. The client provides piactl and keeps /Library/Preferences/com.privateinternetaccess.vpn/settings.json up to date.
2. piactl available somewhere on your system. The installer searches common locations plus whatever is on your PATH.
3. jq for parsing JSON. Install it with brew install jq if you do not already have it.
4. A user that can run sudo commands since installing the watcher places files into /usr/local/bin and edits ~/Library/LaunchAgents.

Installing the watcher

1. Clone or extract this repository anywhere under your user account.

2. From the project root run chmod +x setup.sh uninstall.sh update.sh check_pia_split.sh test_run.sh once if needed.

3. Execute the installer:

   ./setup.sh

   The script refuses to run as root. It verifies macOS, validates that jq, piactl, launchctl, plutil, and sudo are ready, then prompts for your sudo password to install the monitoring script into /usr/local/bin/check_pia_split.sh.

4. The installer also writes a LaunchAgent plist at ~/Library/LaunchAgents/com.<user>.pia-split-tunnel-monitor.plist, pointing to the installed checker with a default interval of 60 seconds. Override the interval by exporting PIA_START_INTERVAL=<seconds> before launching setup.sh.

5. Once the script finishes it reloads the agent automatically. Confirm it is running with launchctl list | grep pia-split-tunnel-monitor. Logs are written to ~/Library/Logs/pia-split-tunnel-monitor.log and .err.

How the checker works

• Reads /Library/Preferences/com.privateinternetaccess.vpn/settings.json every minute by default and extracts splitTunnelEnabled with jq.
• Stores the last known on or off state in ~/.pia_split_tunnel_state so you only get a notification when the state flips to off instead of on every poll.
• Optionally auto repairs the split tunnel setting by calling piactl -u applysettings '{"splitTunnelEnabled":true}' when AUTO_FIX_SPLIT_TUNNEL inside the checker is set to true.
• Displays a macOS notification using osascript the first time it sees the off state, along with a submarine alert sound.

Uninstalling

If you ever want to remove the watcher while keeping PIA installed, run the uninstaller from the project root:

./uninstall.sh

It unloads and deletes the LaunchAgent plist, removes /usr/local/bin/check_pia_split.sh, deletes the state file, and clears the default log files. The script prompts for sudo when removing the binary. Afterward you can run launchctl list | grep pia-split-tunnel-monitor to confirm the agent is gone.

Updating

After pulling new code from this repository, refresh the installed watcher with:

./update.sh

The updater copies the latest check_pia_split.sh into /usr/local/bin, rewrites the embedded piactl path if needed, and reloads the LaunchAgent so it runs the new version without touching your existing plist or logs.

Test run

Want to see what happens before touching your real PIA install? Run the harness:

./test_run.sh

It feeds check_pia_split.sh a temporary settings file, stores state under a temp directory, and echoes the notification text instead of invoking macOS Notification Center. The script walks through an initial enabled state, a disabled state, and recovery so you can watch the transitions and exit codes.

Checking status

• Confirm the LaunchAgent is loaded: launchctl list | grep pia-split-tunnel-monitor. A line with the label indicates macOS will keep the checker running after every reboot.
• Inspect the logs in ~/Library/Logs/pia-split-tunnel-monitor.log and .err for any output. Healthy runs are usually silent, so any new lines typically point to a configuration issue.
• Manually run /usr/local/bin/check_pia_split.sh (or ./test_run.sh) to trigger the logic on demand. Toggle split tunneling off in the PIA app and you should see a notification the next time the checker runs.

Log maintenance

The LaunchAgent writes stdout and stderr to ~/Library/Logs/pia-split-tunnel-monitor.log and .err. The checker automatically trims each file to 256 KiB on every run so they do not grow without bound. Tune or disable the behavior by exporting:

• PIA_LOG_MAX_BYTES=<bytes> to set a custom size cap (default 262144 bytes).
• PIA_TRIM_LOGS=false if you prefer to handle truncation yourself.

You can also override the log paths with PIA_STDOUT_LOG and PIA_STDERR_LOG if you edit the LaunchAgent accordingly.

Troubleshooting tips

• If the installer reports that the PIA settings file is missing, launch the PIA desktop app once and toggle split tunneling so the file exists.
• When notifications never appear, check the permissions on /Library/Preferences/com.privateinternetaccess.vpn/settings.json. Your user must be able to read it without sudo.
• Look at the log files in ~/Library/Logs for any runtime errors. They usually contain the full stderr output from the checker.
• If you relocate piactl, rerun ./setup.sh so the installed script is updated with the new path.

Credits

Joshua Weller (https://joshdw.com)

License

Released under the MIT License. See LICENSE for details.