Skip to main content
Agent skill

Homelab Wireguard Vpn

WireGuard VPN server setup, peer configuration, key generation, split tunneling vs full tunnel routing, and remote access to a home network from mobile and laptop clients. Use when setting up WireGuard for remote access to a home network, or deciding between split and full tunnel routing.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Homelab Wireguard Vpn when an AI agent needs a reusable SKILL.md workflow for this job: WireGuard VPN server setup, peer configuration, key generation, split tunneling vs full tunnel routing, and remote access to a home network from mobile and laptop clients. Use when setting up WireGuard for remote access to a home network, or deciding between split and full tunnel routing.

When not to use it

Skip Homelab Wireguard Vpn when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/homelab-wireguard-vpn
# Save SKILL.md to ~/.claude/skills/homelab-wireguard-vpn/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/homelab-wireguard-vpn/SKILL.md. For a shared project, commit the folder at .claude/skills/homelab-wireguard-vpn/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Homelab Wireguard Vpn skill for this task: Setting up WireGuard server on a Raspberry Pi, Linux host, pfSense, or router. Confirm any required inputs or files before making changes.

What supports this recommendation?

88/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
100/100
Practical detail
100/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Homelab WireGuard VPN

WireGuard is a fast, modern VPN protocol. It is the right choice for remote access to a home network — simpler to configure than OpenVPN and faster than most alternatives.

All configuration examples show common setups. Review each command — especially the iptables forwarding rules and key file permissions — before applying them to your system, and make changes in a maintenance window.

## When to Use

- Setting up WireGuard server on a Raspberry Pi, Linux host, pfSense, or router - Generating WireGuard keypairs and writing peer config files - Configuring remote access from a phone or laptop to a home network - Explaining split tunneling (route only home traffic) vs full tunnel (route all traffic) - Troubleshooting WireGuard connections that will not come up - Automating peer configuration generation for multiple clients

## How WireGuard Works

``` Your phone (WireGuard client) │ │ Encrypted UDP tunnel (port 51820) │ Your home router (WireGuard server — needs a public IP or DDNS) │ Your home network (192.168.1.0/24, NAS, Pi, etc.)

Every device has a keypair (public + private key). The server knows each client's public key. The client knows the server's public key + endpoint (IP:port). Traffic is encrypted end-to-end with no central server or certificate authority. ```

## Server Setup (Linux)

```bash # Install WireGuard sudo apt update && sudo apt install wireguard -y

# Generate server keypair — create files with private permissions from the start sudo mkdir -p /etc/wireguard sudo sh -c 'umask 077; wg genkey > /etc/wireguard/server_private.key' sudo sh -c 'wg pubkey < /etc/wireguard/server_private.key > /etc/wireguard/server_public.key'

# Write server config — substitute the actual private key value # Do not store private keys in version control or share them sudo tee /etc/wireguard/wg0.conf << 'EOF' [Interface] Address = 10.8.0.1/24 # VPN subnet — server gets .1 ListenPort = 51820 PrivateKey = <paste_server_private_key_here>

# Scoped forwarding rules: allow VPN traffic in/out, not a blanket FORWARD ACCEPT PostUp = iptables -A FORWARD -i wg0 -o eth0 -j ACCEPT PostUp = iptables -A FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE PostDown = iptables -D FORWARD -i wg0 -o eth0 -j ACCEPT PostDown = iptables -D FORWARD -i eth0 -o wg0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer] # Phone — replace with the actual phone public key PublicKey = <phone_public_key> AllowedIPs = 10.8.0.2/32

[Peer] # Laptop — replace with the actual laptop public key PublicKey = <laptop_public_key> AllowedIPs = 10.8.0.3/32 EOF sudo chmod 600 /etc/wireguard/wg0.conf

# Replace eth0 with your actual outbound interface name # Check with: ip route show default

# Enable IP forwarding (required for routing traffic through the server) echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf sudo sysctl --system

# Start WireGuard and enable on boot sudo wg-quick up wg0 sudo systemctl enable wg-quick@wg0 ```

## Client Configuration

```bash # Generate a unique keypair for each client device # Run on the client, or on the server and transfer the private key securely — never in plaintext umask 077 wg genkey | tee phone_private.key | wg pubkey > phone_public.key

# Client config file (phone_wg0.conf): [Interface] PrivateKey = <phone_private_key> Address = 10.8.0.2/32 DNS = 192.168.1.2 # Optional: use Pi-hole for DNS over the tunnel

[Peer] PublicKey = <server_public_key> Endpoint = your-home-ip.ddns.net:51820 # Your public IP or DDNS hostname AllowedIPs = 192.168.1.0/24 # Split tunnel: only home network traffic # AllowedIPs = 0.0.0.0/0, ::/0 # Full tunnel: all traffic through VPN

PersistentKeepalive = 25 # Keep NAT hole open (required for mobile clients) ```

## Split Tunnel vs Full Tunnel

``` # Split tunnel: AllowedIPs = 192.168.1.0/24 Only traffic destined for your home network goes through the VPN. Internet traffic (YouTube, Spotify) goes directly — better performance on mobile. Best for: "I just want to reach my NAS and Pi from anywhere."

# Full tunnel: AllowedIPs = 0.0.0.0/0, ::/0 ALL traffic goes through your home internet connection. Useful for: piggybacking home DNS/Pi-hole ad blocking. Downside: home upload speed becomes your bottleneck everywhere.

# Multi-subnet split tunnel (most common homelab use case): AllowedIPs = 192.168.10.0/24, 192.168.20.0/24, 192.168.30.0/24, 10.8.0.0/24 Routes all your VLANs through the tunnel; internet stays direct. ```

## Key Generation and Peer Management

```python import subprocess

def generate_keypair() -> tuple[str, str]: """Generate a WireGuard keypair. Returns (private_key, public_key).""" private = subprocess.check_output(["wg", "genkey"]).decode().strip() public = subprocess.run( ["wg", "pubkey"], input=private.encode(), capture_output=True ).stdout.decode().strip() return private, public

def generate_preshared_key() -> str: return subprocess.check_output(["wg", "genpsk"]).decode().strip()

def build_client_config( client_private_key: str, client_vpn_ip: str, # e.g. "10.8.0.3" server_public_key: str, server_endpoint: str, # e.g. "home.example.com:51820" allowed_ips: str = "192.168.1.0/24", dns: str = "", ) -> str: dns_line = f"DNS = {dns}\n" if dns else "" return f"""[Interface] PrivateKey = {client_private_key} Address = {client_vpn_ip}/32 {dns_line} [Peer] PublicKey = {server_public_key} Endpoint = {server_endpoint} AllowedIPs = {allowed_ips} PersistentKeepalive = 25 """

def build_server_peer_block( client_public_key: str, client_vpn_ip: str, comment: str = "", ) -> str: comment_line = f"# {comment}\n" if comment else "" return f""" {comment_line}[Peer] PublicKey = {client_public_key} AllowedIPs = {client_vpn_ip}/32 """ ```

Keep private keys out of source control. If you use this script, write key material to files with mode 600 and never log or print it.

## pfSense / OPNsense WireGuard

``` # pfSense: VPN → WireGuard → Add Tunnel Interface Keys: Generate (creates keypair automatically) Listen Port: 51820 Interface Address: 10.8.0.1/24

# Add Peer (one per client): Public Key: <client public key> Allowed IPs: 10.8.0.2/32

# Assign the WireGuard interface: Interfaces → Assignments → Add (select wg0) Enable interface, no IP needed (it is set in the tunnel config)

# Firewall rules: WAN → Allow UDP port 51820 inbound (so clients can reach the server) WireGuard interface → Allow traffic to LAN networks you want reachable ```

## DDNS (Dynamic DNS) for Home Servers

Most home internet connections have a dynamic IP. Use DDNS so your VPN endpoint stays reachable after an IP change.

```bash # Option 1: Cloudflare DDNS — store credentials in a secrets file, not inline # docker-compose entry using an env file: ddns-updater: image: qmcgaw/ddns-updater env_file: ./ddns.env # store zone_id and token here, not in compose restart: unless-stopped

# ddns.env (chmod 600, not committed to git): # SETTINGS_CLOUDFLARE_ZONE_ID=your_zone_id # SETTINGS_CLOUDFLARE_TOKEN=your_api_token

# Option 2: DuckDNS (free, simple) Sign up at duckdns.org → get a token and subdomain (myhome.duckdns.org) Store token in /etc/ddns.env (mode 600), then use a small root-owned script:

# /usr/local/bin/update-duckdns #!/bin/sh set -eu . /etc/ddns.env curl --fail --silent --show-error --max-time 10 \ --get "https://www.duckdns.org/update" \ --data-urlencode "domains=myhome" \ --data-urlencode "token=${DUCKDNS_TOKEN}" \ --data-urlencode "ip="

# Cron job: */5 * * * * /usr/local/bin/update-duckdns >/dev/null 2>&1 ```

## Troubleshooting

```bash # Check WireGuard status and last handshake sudo wg show

# If "latest handshake" is never or very old, the tunnel is not connected. # Check: # 1. Is UDP port 51820 open on the router/firewall? sudo ufw status # or check pfSense/UniFi firewall rules

# 2. Is the server public key in the client config correct? sudo wg show wg0 public-key # Compare to what is in the client config

# 3. Is IP forwarding enabled on the server? cat /proc/sys/net/ipv4/ip_forward # Should be 1

# 4. Does the client AllowedIPs cover the IP you are trying to reach? # If AllowedIPs = 192.168.1.0/24 and you are trying to reach 192.168.3.5, it will not route.

# Check kernel logs for WireGuard errors dmesg | grep wireguard

# Restart WireGuard sudo wg-quick down wg0 && sudo wg-quick up wg0 ```

## Anti-Patterns

``` # BAD: Storing private keys in version control or sharing them # Private keys are equivalent to passwords — never commit them to git

# BAD: Using AllowedIPs = 0.0.0.0/0 on mobile without considering the impact # Full tunnel routes all mobile traffic through your home upload — usually slow

# BAD: Not setting PersistentKeepalive on mobile clients # Mobile clients behind NAT drop idle tunnels without it

# BAD: Opening port 51820 in the firewall but forgetting IP forwarding on the server # Tunnel connects but no traffic routes — confusing to debug

# BAD: Sharing a keypair across multiple client devices # Each device must have its own unique keypair — shared keys break the security model

# BAD: Using a broad "FORWARD ACCEPT" iptables rule # Scope forwarding rules to the wg0 interface and direction only ```

## Best Practices

- Generate a unique keypair per client device — never reuse keys - Use split tunneling (`AllowedIPs = <home subnets>`) for mobile - Set `PersistentKeepalive = 25` on all mobile clients - Use DDNS if your ISP assigns a dynamic IP; store credentials in env files, not inline - Use scoped iptables forwarding rules (inbound on wg0 only) rather than a blanket FORWARD ACCEPT - Add Pi-hole's IP as `DNS =` in client configs to get ad blocking over the VPN - Rotate the server keypair periodically and update all client configs

## Related Skills

- homelab-network-setup - homelab-vlan-segmentation - homelab-pihole-dns

Intended uses

  • Setting up WireGuard server on a Raspberry Pi, Linux host, pfSense, or router
  • Generating WireGuard keypairs and writing peer config files
  • Configuring remote access from a phone or laptop to a home network
  • Explaining split tunneling (route only home traffic) vs full tunnel (route all traffic)
  • Troubleshooting WireGuard connections that will not come up
  • Automating peer configuration generation for multiple clients

Implementation notes

  • Generate a unique keypair per client device — never reuse keys
  • Use split tunneling (AllowedIPs = <home subnets>) for mobile
  • Set PersistentKeepalive = 25 on all mobile clients
  • Use DDNS if your ISP assigns a dynamic IP; store credentials in env files, not inline
  • Use scoped iptables forwarding rules (inbound on wg0 only) rather than a blanket FORWARD ACCEPT
  • Add Pi-hole's IP as DNS = in client configs to get ad blocking over the VPN
  • Rotate the server keypair periodically and update all client configs

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.