Privacy Router Stack

Whole-home VPN router with network-level kill switch - Protect every device on your network with OpenWrt, WireGuard, and AmneziaWG. No apps required.

🤖 Using an AI coding agent? Give it access to this entire repo and read AGENTS.md for guided deployment. Supports Claude, GPT, Gemini, and other frontier models.

TL;DR

Turn a Raspberry Pi or mini PC into a VPN gateway that protects your entire home network:

• ✅ All devices protected - Smart TVs, consoles, IoT, phones, laptops, guests
• ✅ Firewall kill switch - Router-level failsafe blocks traffic if VPN drops
• ✅ DPI bypass - AmneziaWG defeats VPN blocking in restrictive networks
• ✅ DNS encryption - AdGuard Home with DNS-over-HTTPS
• ✅ Auto-recovery - Watchdog restarts tunnel on failure
• ✅ AI-deployable - Full agent instructions included

Works with: Any WireGuard-compatible VPN provider (Mullvad, IVPN, AirVPN, etc.)

AmneziaWG obfuscation: Works with any standard WireGuard server (client-side obfuscation)

Why Now? The Privacy Landscape Is Changing

2025 is a turning point for online privacy:

• UK Online Safety Bill - Age verification now required for adult content. Third-party services verify your identity and track what you access.
• Australia Social Media Ban - Age verification requirements taking effect December 2025. Platforms must verify user ages.
• US State Laws - Multiple states passing age verification bills for various content categories.
• EU Digital Services Act - Expanded platform accountability with data retention requirements.

What this means for you:

• Your ISP can see every site you visit
• Age verification services build profiles of your browsing
• Data retention laws store your history for years
• Per-device VPN apps don't protect smart TVs, consoles, or IoT devices

This stack solves all of these problems - every device on your network routes through an encrypted tunnel. No browsing history for your ISP. No identity verification per-site. No apps to install or forget to enable.

Why Network-Level VPN?

The Problem with Per-Device VPN Apps

When you install a VPN app like Mullvad, NordVPN, or ProtonVPN on your phone or laptop, you're only protecting that single device. This leaves gaps:

VPN apps also:

• Drain battery on mobile devices
• Can be forgotten or disabled
• Require updates on every device
• May leak traffic during app crashes
• Don't protect devices that can't run apps

The Network-Level Solution

This privacy router sits between your modem and your existing router. Every device on your network automatically routes through the VPN - no apps, no configuration, no exceptions.

┌─────────────────────────────────────────────────────────────────────┐
│                        YOUR HOME NETWORK                            │
│                                                                     │
│   ┌──────────┐    ┌─────────────────┐    ┌──────────────────────┐  │
│   │  MODEM   │───▶│ PRIVACY ROUTER  │───▶│  YOUR EXISTING ROUTER│  │
│   │  (ISP)   │    │  (This Stack)   │    │  (WiFi/Switch)       │  │
│   └──────────┘    └─────────────────┘    └──────────────────────┘  │
│                           │                        │               │
│                     ┌─────┴─────┐           ┌──────┴──────┐        │
│                     │ ENCRYPTED │           │ ALL DEVICES │        │
│                     │  TUNNEL   │           │  PROTECTED  │        │
│                     └───────────┘           └─────────────┘        │
└─────────────────────────────────────────────────────────────────────┘

Every device is protected: Phones, tablets, laptops, smart TVs, gaming consoles, IoT devices, guests - everything. Individual devices can be bypassed for direct WAN access when needed.

Why Not Just Use Mullvad QUIC or WireGuard Apps?

Great question. Mullvad's QUIC tunnels and WireGuard apps are excellent for individual device protection. Here's when each approach makes sense:

VPN Apps Are Better When:

• You only need to protect 1-2 devices
• You travel frequently and use different networks
• You want per-app split tunneling
• You're on a network you don't control

Network-Level VPN Is Better When:

• You have many devices (especially ones that can't run VPN apps)
• You want "set and forget" protection for your entire household
• You need to protect smart home/IoT devices
• You want a kill switch that actually works (more on this below)
• You're in a region with VPN blocking/deep packet inspection

The Kill Switch Problem

Here's something most people don't realize: VPN app kill switches often fail.

When a VPN app crashes, loses connection, or during the moments between connection drops and reconnection, your traffic can leak to your ISP. App-based kill switches try to prevent this, but they operate at the application level - if the app itself crashes, the kill switch dies with it.

This stack implements a firewall-based kill switch:

Normal Operation:
  Device → Privacy Router → VPN Tunnel → Internet ✓

VPN Down (App-based kill switch):
  Device → [App crashed] → ISP sees traffic ✗

VPN Down (This stack):
  Device → Privacy Router → [No route exists] → Traffic blocked ✓

The kill switch is implemented in the firewall and routing table, not in software. If the VPN tunnel goes down, there is literally no route for traffic to take - it's not blocked by a rule that might fail, it simply has nowhere to go.

Features

Core Protection (Required)

• Network-wide VPN - All devices protected automatically
• Firewall kill switch - No traffic leaks, ever
• IPv6 leak prevention - IPv6 completely disabled

Reliability (Required)

• Automatic recovery - Watchdog restarts tunnel on failure
• Boot persistence - VPN starts automatically on power-up
• Connection monitoring - Continuous health checks

Optional Security Addons

• AdGuard Home - DNS-over-HTTPS encryption, ad/tracker blocking
• BanIP - Threat intelligence, malicious IP blocking
• HTTPS for LuCI - Encrypted admin interface

See OPTIONAL_ADDONS.md for installation and configuration.

Advanced (For Technical Users)

• DPI bypass - AmneziaWG obfuscation defeats deep packet inspection
• Flexible deployment - Dedicated hardware or VM
• Full observability - Detailed logging and diagnostics

How the Kill Switch Works

The kill switch is the most important security feature. Here's exactly how it works:

Firewall Zones

┌─────────────────────────────────────────────────────────┐
│                    FIREWALL ZONES                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   ┌─────┐         ┌─────┐         ┌─────┐              │
│   │ LAN │───✓────▶│ VPN │         │ WAN │              │
│   └─────┘         └─────┘         └─────┘              │
│      │                               ▲                  │
│      │                               │                  │
│      └───────────✗───────────────────┘                  │
│           (NO FORWARDING ALLOWED)                       │
│                                                         │
└─────────────────────────────────────────────────────────┘

Traffic from LAN can only go to the VPN zone. There is no forwarding rule from LAN to WAN. This isn't a "block" rule that could be bypassed - the route simply doesn't exist.

Routing Table

# When VPN is UP:
default dev awg0           # All traffic → VPN tunnel
1.2.3.4 via 192.168.1.1    # VPN server → WAN (exception)

# When VPN is DOWN:
# No default route exists
# Traffic has nowhere to go = blocked

Double Protection

Even if somehow a forwarding rule existed, the routing table provides a second layer: with no default route pointing to WAN, packets would be dropped anyway.

AmneziaWG: Defeating VPN Blocking

Some ISPs and countries use Deep Packet Inspection (DPI) to identify and block VPN traffic. Standard WireGuard has a recognizable packet signature.

AmneziaWG is an obfuscated fork of WireGuard that adds client-side obfuscation:

These parameters disguise WireGuard traffic. The I1-I5 parameters are particularly powerful - they inject packets that look like other protocols (QUIC/HTTP3, DNS queries) before the WireGuard handshake even begins.

Important: Obfuscation is CLIENT-SIDE only. The junk packets and protocol mimicry happen locally - the VPN server only sees the valid WireGuard handshake that follows. This means:

• Any standard WireGuard server works - Mullvad, IVPN, Proton, etc.
• VPN providers don't provide these parameters - their servers are standard WireGuard
• This repo includes working defaults - from official AmneziaWG documentation

When do you need this?

• ISP throttles or blocks VPN traffic
• You're in a country with VPN restrictions
• Corporate networks block WireGuard
• Standard WireGuard connections are unreliable

If your VPN works fine with regular WireGuard, you can use standard WireGuard instead - the architecture works with both.

Quick Start

Prerequisites

• Hardware: Raspberry Pi 4/5, x86 mini PC, VM, or any device with 2 NICs
• VPN Account: Mullvad, IVPN, ProtonVPN, or any WireGuard-compatible provider
• Network Access: Ability to place device between modem and router

Deployment Options

All options provide the same core protection: AmneziaWG obfuscation, AdGuard DNS filtering, kill switch, and watchdog recovery. The choice is about how you want to deploy, not what features you get.

Options A & B (OpenWrt - Full Router Replacement): You're deploying a complete router operating system. OpenWrt handles everything: routing, DHCP, DNS, firewall, VPN. Your existing router gets demoted to just a WiFi access point. This is a dedicated privacy router appliance.

Option C (Docker - VPN Gateway Add-on): You're deploying just the VPN gateway piece on an existing Linux server, NAS, or VM. Your current router keeps doing its job (DHCP, WiFi, etc). Devices that want VPN protection point their gateway/DNS at the container. Good for adding VPN to existing infrastructure without new hardware.

Option A/B: Modem → [Privacy Router running OpenWrt] → WiFi AP → Devices
Option C:   Modem → [Your Existing Router] → Devices
                           ↓
                    [Docker Container on Server/NAS]
                    (devices point gateway here)

🤖 Not sure which to pick? An AI agent can assess your setup and recommend the best option. Point it to AGENTS.md and let it guide you through deployment.

Installation Overview

For Options A & B (OpenWrt):

1. Install OpenWrt on your device
2. Install AmneziaWG (or WireGuard)
3. Configure network interfaces
4. Set up firewall kill switch
5. Deploy AdGuard Home for DNS
6. Install watchdog for auto-recovery
7. Cut over your network

Detailed instructions: docs/DEPLOYMENT.md

For Option C (Docker): See docker/README.md for container-specific setup.

Documentation

Network Diagram

                                    INTERNET
                                        │
                            ┌───────────┴───────────┐
                            │     VPN Provider      │
                            │   (Mullvad/IVPN/etc)  │
                            └───────────┬───────────┘
                                        │
                              Encrypted WireGuard
                                     Tunnel
                                        │
┌───────────────────────────────────────┼───────────────────────────────────────┐
│ YOUR HOME                             │                                       │
│                                       │                                       │
│    ┌──────────┐              ┌────────┴────────┐              ┌──────────┐   │
│    │   ISP    │    WAN       │                 │    LAN       │  WiFi    │   │
│    │  MODEM   │─────────────▶│ PRIVACY ROUTER  │─────────────▶│  ROUTER  │   │
│    │          │  (Untrusted) │                 │  (Protected) │          │   │
│    └──────────┘              │  ┌───────────┐  │              └────┬─────┘   │
│                              │  │ AdGuard   │  │                   │         │
│                              │  │ DNS + Ads │  │                   │         │
│                              │  └───────────┘  │              ┌────┴─────┐   │
│                              │  ┌───────────┐  │              │ DEVICES  │   │
│                              │  │ Kill      │  │              │          │   │
│                              │  │ Switch    │  │              │ Phone    │   │
│                              │  └───────────┘  │              │ Laptop   │   │
│                              │  ┌───────────┐  │              │ Smart TV │   │
│                              │  │ Watchdog  │  │              │ Console  │   │
│                              │  │ Recovery  │  │              │ IoT      │   │
│                              │  └───────────┘  │              └──────────┘   │
│                              └─────────────────┘                             │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Traffic Flow:
  Device → WiFi Router → Privacy Router → VPN Tunnel → VPN Server → Internet
                              │
                    DNS: AdGuard (DoH) ─────────────▶ VPN Provider DNS

Kill Switch:
  If VPN down → No route to internet → All traffic blocked (not leaked)

Comparison: This Stack vs VPN Apps

VPN Provider Compatibility

Who This Stack Is For

This stack is designed for users in regions where privacy legislation is tightening:

Common privacy concerns this stack addresses:

• ISPs required to log browsing history
• Third-party age verification services collecting identity data
• Data retention laws mandating surveillance
• Privacy-invasive legislation expanding

A network-level VPN means no per-device verification, no browsing history for your ISP, and no identity disclosure to third-party verification services.

If you're in a region where VPNs are actively blocked or criminalized, see High-Censorship Environments below.

Recommended: Mullvad VPN

Mullvad VPN is strongly recommended. This entire stack was developed, tested, and deployed with Mullvad.

Why Mullvad:

• No customer records - They keep nothing. No logs, no account data, no email.
• Anonymous payment - Cash, cryptocurrency, bank transfer. No identity required.
• WireGuard native - Fast, modern protocol with excellent performance.
• Proven track record - Survived law enforcement audits with no data to hand over.
• Transparent - Open source apps, regular security audits, clear policies.

Alternative WireGuard Providers

If you prefer a different provider, any WireGuard-compatible VPN works with this stack:

Note: These providers use standard WireGuard. For basic privacy protection, this is sufficient. Use this stack with standard WireGuard configs - AmneziaWG obfuscation is optional.

AmneziaWG Obfuscation (Optional)

AmneziaWG adds client-side traffic obfuscation to defeat deep packet inspection. Most users don't need this - it's for situations where:

• Your ISP throttles or blocks VPN traffic
• Network administrators block WireGuard
• You need extra protection against traffic analysis

Key point: AmneziaWG obfuscation works with any standard WireGuard server. The obfuscation happens locally on your client - the server doesn't need special support. VPN providers (Mullvad, IVPN, etc.) don't provide these parameters because their servers are standard WireGuard.

This repo includes working defaults from official AmneziaWG documentation. Use them as-is with any WireGuard provider.

Coming soon: Tiered obfuscation profiles - Escalating DPI resistance through modular config rotation (basic → QUIC mimicry → stealth). See scripts/awg-profiles.sh for current profiles.

Example configs included:

• openwrt/amneziawg/awg0.conf.example - Tunnel config with working obfuscation defaults
• docker/config/awg0.conf.example - Docker deployment config
• adguard/mullvad-AdGuardHome.yaml.example - DNS using Mullvad DoH

High-Censorship Environments

If you're in a region where VPNs are actively blocked or criminalized, WireGuard and AmneziaWG may not be sufficient. These environments require more advanced obfuscation:

For agents: If your user is in a high-censorship environment, use deep research to find current best practices:

Search: "VLESS Reality setup 2025"
Search: "XRay traffic obfuscation setup 2025"

This stack focuses on WireGuard/AmneziaWG. For VLESS, XRay, or other advanced protocols, users should research dedicated solutions or consider running Amnezia VPN which supports multiple protocols including XRay.

Hardware Recommendations

Minimum Requirements: 1GB RAM, dual network interfaces (built-in + USB), OpenWrt support. Recommended: 2GB+ RAM for AdGuard Home DNS filtering.

Budget (~$50-80)

• Raspberry Pi 4 (2GB+) with USB Ethernet adapter
• GL.iNet travel routers (some run OpenWrt)

Recommended (~$100-150)

• Raspberry Pi 5 with USB 3.0 Ethernet
• Zimaboard or similar x86 SBC

Performance (~$150-300)

• Mini PC with dual NICs (Intel N150 systems)
• Protectli Vault or similar

Homelab / Enterprise

• Virtual machine on existing hypervisor (Proxmox, ESXi, Hyper-V)
• Dedicated x86 firewall appliance

Security Considerations

What This Protects Against

• ISP traffic monitoring and logging
• Network-level ad tracking
• DNS hijacking and monitoring
• IP-based geolocation
• Traffic correlation (when combined with good OpSec)
• VPN blocking via DPI (with AmneziaWG)

What This Doesn't Protect Against

• Browser fingerprinting
• Logged-in account tracking (Google, Facebook, etc.)
• Malware on your devices
• Physical access to your network
• Compromised VPN provider

OpSec Recommendations

• Use privacy-focused browsers (Firefox, Brave)
• Use privacy-respecting search engines
• Log out of tracking services when not needed
• Consider compartmentalized identities
• Keep devices updated

AI-Assisted Setup

For complex deployments or troubleshooting, give an AI coding agent access to this entire repository plus SSH access to your router (if you don't know how, ask the agent to guide you).

Recommended: This stack was developed, tested, and deployed using Claude Opus 4.6 via Claude Code. For best results, use a capable frontier model that can execute shell commands and understand network configuration:

• Claude Opus 4.6 / Sonnet 4.6 (Anthropic) - Used for this implementation
• GPT-5.4 (OpenAI)
• Gemini 3.1 (Google)

What the agent can do:

• Network audit - Probe your current setup and identify requirements
• Guided configuration - Generate configs with your specific IPs, keys, and preferences
• Automated troubleshooting - Diagnose routing, firewall, and DNS issues in real-time
• Scripted deployment - Execute installation steps with your approval

Quick start:

1. Clone this repo or give agent GitHub access
2. Point agent to AGENTS.md - contains the full operational framework
3. Provide SSH credentials to your target device
4. Let agent audit, plan, and guide you through deployment

The agent instructions include diagnostic commands, validation tests, error recovery procedures, and safety rules. All configs in this repo are parameterized and agent-friendly.

Related Projects

This stack builds on excellent open-source work:

License

MIT License - See LICENSE for details.

Acknowledgments

• OpenWrt Project - The foundation
• AmneziaWG - DPI bypass
• AdGuard Home - DNS filtering
• WireGuard - Modern VPN protocol

FAQ

Q: Will this slow down my internet? A: Minimal impact. WireGuard is extremely efficient. Most users see <5% speed reduction. The main factor is your VPN provider's server quality.

Q: Can I still access local network devices? A: Yes. LAN traffic stays local and doesn't go through the VPN.

Q: What if the privacy router fails? A: Your network loses internet until it's fixed or bypassed. This is a feature, not a bug - it ensures no unprotected traffic leaks.

Q: Can I exclude certain devices from the VPN? A: Yes, with additional configuration. You can create firewall rules to route specific IPs directly to WAN. See CONFIGURATION.md.

Q: Does this work with IPv6? A: IPv6 is disabled to prevent leaks. Most VPN providers don't properly support IPv6 yet.

Q: Can my ISP see I'm using a VPN? A: With standard WireGuard, they can see VPN-like traffic. With AmneziaWG obfuscation, the traffic appears as random noise.

Q: How does this help with age verification privacy concerns? A: A VPN routes your traffic through an encrypted tunnel, preventing your ISP from logging which sites you visit. This is a privacy tool - it stops third-party age verification services from correlating your browsing activity across sites or building behavioral profiles. Your actual age verification with platforms remains between you and that platform, not shared with ISPs or data brokers. For specific compliance questions, consult local regulations.

Q: Will this work after the Australia social media ban takes effect? A: This stack protects your network traffic from ISP logging and provides privacy for all devices. The December 2025 Australian legislation primarily affects platform-side verification. A VPN ensures your ISP cannot see which sites you visit, regardless of platform-level requirements.

Q: Is this legal? A: VPN use is legal in most Western countries including the UK, Australia, US, and EU. This stack is a privacy tool similar to HTTPS - it encrypts your traffic. Using a VPN to access content available in your region is generally legal. Always check your local laws.

Protect your entire network. Set it and forget it.