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.
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)
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.
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:
| Device | VPN App Support | Risk |
|---|---|---|
| Smart TV | ❌ None | ISP sees all streaming |
| Gaming Console | ❌ None | IP exposed to game servers |
| IoT Devices | ❌ None | Smart home traffic visible |
| Guest Devices | ❌ Can't control | No protection |
| Work Laptop | Corporate policy blocks VPN | |
| Kids' Devices | Protection bypassed |
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
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.
Great question. Mullvad's QUIC tunnels and WireGuard apps are excellent for individual device protection. Here's when each approach makes sense:
- 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
- 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
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.
- Network-wide VPN - All devices protected automatically
- Firewall kill switch - No traffic leaks, ever
- IPv6 leak prevention - IPv6 completely disabled
- Automatic recovery - Watchdog restarts tunnel on failure
- Boot persistence - VPN starts automatically on power-up
- Connection monitoring - Continuous health checks
- 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.
- DPI bypass - AmneziaWG obfuscation defeats deep packet inspection
- Flexible deployment - Dedicated hardware or VM
- Full observability - Detailed logging and diagnostics
The kill switch is the most important security feature. Here's exactly how it works:
┌─────────────────────────────────────────────────────────┐
│ 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.
# 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 = blockedEven 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.
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:
| Parameter | Purpose |
|---|---|
| Jc, Jmin, Jmax | Junk packets sent before handshake |
| H1-H4 | Header obfuscation values |
| S1-S4 | Packet padding sizes |
| I1-I5 | Protocol mimicry blobs (QUIC, DNS, etc.) |
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.
- 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
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.
| Option | What You're Deploying | Your Existing Router |
|---|---|---|
| A: Dedicated Hardware | Full router OS (OpenWrt) on Pi/mini PC | Becomes WiFi access point only |
| B: Virtual Machine | Full router OS (OpenWrt) on Proxmox/ESXi | Becomes WiFi access point only |
| C: Docker Container | VPN gateway only (Alpine container) | Keeps all its current functions |
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.
For Options A & B (OpenWrt):
- Install OpenWrt on your device
- Install AmneziaWG (or WireGuard)
- Configure network interfaces
- Set up firewall kill switch
- Deploy AdGuard Home for DNS
- Install watchdog for auto-recovery
- Cut over your network
Detailed instructions: docs/DEPLOYMENT.md
For Option C (Docker): See docker/README.md for container-specific setup.
| Document | Description |
|---|---|
| ARCHITECTURE.md | System design, components, security model |
| HOW-IT-WORKS.md | Deep technical dive into every component |
| DEPLOYMENT.md | Step-by-step installation guide |
| docker/README.md | Docker deployment (advanced users) |
| CONFIGURATION.md | Complete configuration reference |
| OPTIONAL_ADDONS.md | AdGuard Home, BanIP, and other security addons |
| TROUBLESHOOTING.md | Common issues and solutions |
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)
| Feature | VPN App | This Stack |
|---|---|---|
| Devices protected | 1 per install | All on network |
| Smart TV/Console | ❌ | ✓ |
| IoT devices | ❌ | ✓ |
| Battery impact | Yes | None |
| Can be disabled | By user | No |
| Kill switch reliability | App-dependent | Firewall-based |
| DNS leak protection | Varies | Guaranteed |
| DPI bypass | Some apps | AmneziaWG |
| Setup complexity | Low | Medium |
| Ongoing maintenance | Per device | Centralized |
This stack is designed for users in regions where privacy legislation is tightening:
| Region | Legislation | Impact |
|---|---|---|
| UK | Online Safety Bill (2025) | Age verification required for adult content; third-party ID services track access |
| Australia | Social Media Age Verification (Dec 2025) | Under-16 ban with verification requirements |
| EU | Digital Services Act | Platform accountability with data retention |
| US States | Various age verification bills | State-level ID requirements expanding |
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.
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.
If you prefer a different provider, any WireGuard-compatible VPN works with this stack:
| Provider | Privacy | Notes |
|---|---|---|
| IVPN | No logs, open source | Good Mullvad alternative |
| AirVPN | No logs, port forwarding | Standard WireGuard only (no AmneziaWG) |
| ProtonVPN | No logs (all tiers) | Free tier available |
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 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.
| Option | Setup | Best For |
|---|---|---|
| Any WireGuard provider | Use default params in this repo | Most users needing obfuscation |
| Self-hosted AmneziaWG | Configure matching params both sides | Custom server setups |
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 defaultsdocker/config/awg0.conf.example- Docker deployment configadguard/mullvad-AdGuardHome.yaml.example- DNS using Mullvad DoH
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:
| Protocol | Description |
|---|---|
| VLESS + Reality | Traffic appears as normal HTTPS to major websites |
| XRay | Advanced proxy with multiple obfuscation modes |
| ShadowSocks | Encrypted proxy designed for restricted network environments |
| Tor + Bridges | Anonymity network with pluggable transports |
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.
Minimum Requirements: 1GB RAM, dual network interfaces (built-in + USB), OpenWrt support. Recommended: 2GB+ RAM for AdGuard Home DNS filtering.
- Raspberry Pi 4 (2GB+) with USB Ethernet adapter
- GL.iNet travel routers (some run OpenWrt)
- Raspberry Pi 5 with USB 3.0 Ethernet
- Zimaboard or similar x86 SBC
- Mini PC with dual NICs (Intel N150 systems)
- Protectli Vault or similar
- Virtual machine on existing hypervisor (Proxmox, ESXi, Hyper-V)
- Dedicated x86 firewall appliance
- 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)
- Browser fingerprinting
- Logged-in account tracking (Google, Facebook, etc.)
- Malware on your devices
- Physical access to your network
- Compromised VPN provider
- 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
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.5 via Claude Code. For best results, use a capable frontier model that can execute shell commands and understand network configuration:
- Claude Opus 4.5 / Sonnet 4.5 (Anthropic) - Used for this implementation
- GPT-5.1 (OpenAI)
- Gemini 3 (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:
- Clone this repo or give agent GitHub access
- Point agent to AGENTS.md - contains the full operational framework
- Provide SSH credentials to your target device
- 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.
This stack builds on excellent open-source work:
| Project | Description |
|---|---|
| amnezia-vpn/amneziawg-linux-kernel-module | AmneziaWG kernel module |
| amnezia-vpn/amneziawg-tools | AmneziaWG userspace tools |
| Slava-Shchipunov/awg-openwrt | Pre-built AmneziaWG packages for OpenWrt |
| wgtunnel/wgtunnel | WireGuard tunnel management |
MIT License - See LICENSE for details.
- OpenWrt Project - The foundation
- AmneziaWG - DPI bypass
- AdGuard Home - DNS filtering
- WireGuard - Modern VPN protocol
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.
