Accessing your home network remotely should not require complex configuration files, opaque encryption handshakes, or expensive enterprise VPN appliances. WireGuard has revolutionized personal VPN infrastructure by replacing legacy protocols like OpenVPN and IPsec with a lean, state-of-the-art codebase. With just ~4,000 lines of kernel code compared to OpenVPN's ~100,000, WireGuard delivers near-instant connection handshakes, battery-friendly mobile standby, and maximum bandwidth utilization.

PiVPN is the gold-standard automated installer designed specifically to deploy and manage WireGuard on Raspberry Pi OS. It handles firewall rules, IP forwarding, client key generation, dynamic DNS, and mobile QR code provisioning with simple terminal commands.

This guide walks you through hardware requirements, installing WireGuard with PiVPN, configuring router UDP port forwarding, creating client profiles with mobile QR codes, split-tunnel vs full-tunnel routing, and securing your installation.

Hardware planning and prerequisites

  • Recommended Board: A Raspberry Pi 4 or Raspberry Pi 5 connected via gigabit Ethernet delivers maximum VPN throughput (often exceeding 500+ Mbps depending on your home internet upload speed). A Raspberry Pi 3 or Zero 2 W can also handle personal WireGuard traffic efficiently.
  • Operating System: A clean installation of Raspberry Pi OS (64-bit) with standard administrative privileges.
  • Public IP & Port Forwarding: Because PiVPN hosts a direct VPN server, you need a public IPv4 address (not behind Carrier-Grade NAT/CGNAT) and access to your home router to forward a single UDP port.
  • Dynamic DNS (DDNS): If your home ISP changes your public IP address periodically, configure a free Dynamic DNS hostname (using DuckDNS, No-IP, or Cloudflare DDNS) so your mobile profiles always connect to the correct endpoint.

Set a static IP on your Raspberry Pi before proceeding:

BASH
sudo apt update && sudo apt upgrade -y
ip -4 addr show

Install WireGuard using PiVPN

Run the official PiVPN automated installer:

BASH
curl -fsSL https://install.pivpn.io | bash

The terminal interface will guide you through key configuration decisions: 1. User Account: Select your default Raspberry Pi user account to store client VPN profiles. 2. VPN Protocol: Choose WireGuard (strongly recommended over OpenVPN for superior speed and mobile battery life). 3. Default Port: The standard WireGuard port is 51820 (UDP). You can keep this default or choose an alternate high port. 4. DNS Provider: Select the DNS server VPN clients will query. If you run Pi-hole on the same Pi, select it here to enjoy network-wide ad blocking on mobile cellular data! 5. Public IP or DNS Name: Select DNS Name and enter your Dynamic DNS address (for example, myhome.duckdns.org). This ensures your clients can reconnect even if your ISP assigns a new public IP. 6. Reboot: Allow the installer to reboot the Raspberry Pi to load the WireGuard kernel module and apply sysctl packet forwarding rules.

Configure Router UDP Port Forwarding

For incoming VPN connections to reach your Raspberry Pi: 1. Open your home router's administration portal. 2. Navigate to Port Forwarding / Virtual Server. 3. Create a new rule forwarding external port 51820 (Protocol: UDP only) to your Raspberry Pi's local static IP (e.g., 192.168.1.50).

Security reminder: WireGuard is completely silent to port scans. If a client attempts to connect without a cryptographically valid public key, WireGuard does not respond with any handshake or acknowledgment packet. To an automated scanner, the port appears completely closed.

Generating Client Profiles and Mobile QR Codes

PiVPN includes simple CLI utilities to manage client profiles.

Generate a profile for your phone:

BASH
pivpn add

Enter a friendly client name (for example, phone-alex). PiVPN automatically creates the cryptographic keypair and generates an optimized .conf file in $HOME/ovpns/ (or $HOME/configs/).

Display a scannable QR code directly in your terminal:

BASH
pivpn -qr phone-alex
  1. Install the official WireGuard app from the iOS App Store or Google Play Store.
  2. Open the app, tap Add a tunnel (+), and select Create from QR code.
  3. Scan the terminal QR code, name the tunnel, and toggle it on.

Your mobile phone is now securely tunneled into your home network. You can reach local devices at http://192.168.1.x and browse the web with your home IP address.

Split-Tunnel vs Full-Tunnel Configurations

Client configuration files specify which traffic routes through the VPN via the AllowedIPs parameter:

Full-Tunnel (Maximum Security on Public Wi-Fi)

In full-tunnel mode, 100% of all internet and local network traffic is encrypted and routed through your Raspberry Pi:

INI
AllowedIPs = 0.0.0.0/0, ::/0

Use full-tunnel when connecting to untrusted hotel, airport, or coffee shop Wi-Fi networks.

Split-Tunnel (Home LAN Access Only)

In split-tunnel mode, only requests destined for your home subnet route through the VPN; general web browsing, video streaming, and app updates use your mobile phone's normal internet connection:

INI
AllowedIPs = 192.168.1.0/24, 10.6.0.0/24

This conserves home broadband upload bandwidth and reduces mobile latency for everyday browsing while maintaining full access to home servers.

Managing Clients and Security

PiVPN provides commands to monitor and revoke connected devices:

List all generated clients and their active handshake timestamps:

BASH
pivpn list

Revoke access for a lost or replaced device:

BASH
pivpn remove phone-alex

Keep your system and WireGuard packages updated:

BASH
sudo apt update && sudo apt upgrade -y

Monitor WireGuard with Open Pi

Monitoring your Raspberry Pi VPN server ensures you are alerted to packet loss, storage issues, or excessive data consumption.

With Open Pi on your iOS or Android device: - Interface Throughput: Monitor incoming and outgoing traffic rates on wg0 and physical Ethernet. - CPU & Thermal Metrics: Confirm that multi-client cryptographic tunneling does not elevate core temperatures. - System Service Status: Verify that the wg-quick@wg0 systemd service remains active.

Troubleshooting WireGuard connections

When your mobile client fails to connect:

  • Handshake Did Not Complete: If the WireGuard app shows packets sent but 0 packets received, the handshake failed. Verify that your router's UDP port forwarding rule points to the correct local IP and that your Dynamic DNS resolves to your current public IP.
  • Carrier-Grade NAT (CGNAT) Issues: If your ISP uses CGNAT (your WAN IP begins with 100.64.x.x), incoming ports cannot be forwarded from the internet. In this case, use Tailscale instead of PiVPN, as Tailscale handles CGNAT traversal automatically.
  • MTU Fragmentation on Cellular Networks: Certain mobile carriers (such as T-Mobile or Vodafone) have lower MTU limits on IPv6 mobile data, causing VPN connections to stall on large pages. Open your client profile in the WireGuard app and adjust the MTU setting to 1280 or 1360.

Sources and further reading

Open Pi logo
Monitor your Raspberry Pi from your phone

Check real-time CPU, RAM, temperature, and service health for your networking projects with Open Pi for iOS and Android. Local-first, private, and no cloud account required.

Explore Open Pi App StoreGoogle Play
About this guide

Researched and validated against official project documentation and community standards on September 11, 2026. Review your board model, storage, and current release notes before deploying.