---
name: vpn-management
description: Manage WireGuard VPN connections via wg-quick.
---

# VPN Management (WireGuard)

This skill provides a way to manage WireGuard VPN connections using `wg-quick`. It includes scripts for turning the connection on and off, as well as handling sudo requirements.

For complete WireGuard removal (when switching to Clash/proxy), see `references/wireguard-removal.md`.

## Usage
- **Turn ON**: `bash ~/wg-on.sh` (Runs `sudo wg-quick up wg0`)
- **turn OFF**: `bash ~/wg-off.sh` (Runs `sudo wg-quick down wg0`)

## Pitfalls
- **⚠️ TEST BEFORE EXECUTE — WireGuard can kill all connectivity instantly.** `wg-quick up wg0` with full-tunnel config (`AllowedIPs = 0.0.0.0/0`) routes ALL traffic through the VPN the moment it activates. If the VPN endpoint is unreachable or misconfigured, the machine loses all network access (including SSH). **Always verify before acting**: (1) `ip route` — check current routing, (2) `wg show` — check if interface already exists, (3) `ping <vpn-endpoint>` — confirm the WireGuard server is reachable, (4) after activating, immediately `ping 8.8.8.8` to confirm connectivity. If you lose access, you need physical console or a pre-existing SSH session to run `wg-quick down wg0`.
- **Sudo requirement**: Both commands require `sudo`. If running in a non-interactive terminal, ensure your environment handles the password prompt or use `sudo -S` if you modify the scripts.
- **Interface name**: These scripts target `wg0`. If your interface name is different, update the scripts or use the appropriate command.
- **Command not found**: If `wg-on` or `wg-off` (without `.sh`) is preferred, ensure they are added to your shell's `PATH` or set as aliases.
