https://github.com/lousclues-labs/shroud
A provider-agnostic VPN connection manager for Linux: kill switch, auto-reconnect, system tray, zero telemetry.
https://github.com/lousclues-labs/shroud
kill-switch linux network-manager openvpn privacy system-tray vpn wireguard
Last synced: 21 days ago
JSON representation
A provider-agnostic VPN connection manager for Linux: kill switch, auto-reconnect, system tray, zero telemetry.
- Host: GitHub
- URL: https://github.com/lousclues-labs/shroud
- Owner: lousclues-labs
- License: other
- Created: 2026-01-19T04:12:12.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-24T01:24:12.000Z (22 days ago)
- Last Synced: 2026-05-24T03:13:05.225Z (22 days ago)
- Topics: kill-switch, linux, network-manager, openvpn, privacy, system-tray, vpn, wireguard
- Language: Rust
- Homepage: https://vpnshroud.org
- Size: 1.96 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Governance: GOVERNANCE.md
- Notice: NOTICE
Awesome Lists containing this project
README
# VPN Shroud
[](https://github.com/lousclues-labs/shroud/actions/workflows/ci.yml)
[](https://github.com/lousclues-labs/shroud/actions/workflows/scheduled.yml)
[](CHANGELOG.md)
[](https://www.rust-lang.org/)
[](LICENSE)
**A provider-agnostic VPN connection manager for Linux.**
A **lock shroud** is the protective metal casing around a padlock's shackle. It doesn't replace the lock. It protects the lock from attack.
```
┌─────────────────────────────────────────┐
│ │
│ ┌───────────┐ │
│ │ SHROUD │ ← Protective │
│ │ ┌───────┐ │ outer casing │
│ │ │ LOCK │ │ │
│ │ │MECHANISM│ ← The vulnerable │
│ │ └───────┘ │ internals │
│ └───────────┘ │
│ │
└─────────────────────────────────────────┘
```
That's what VPN Shroud does:
| Lock Shroud | VPN Shroud (This Tool) |
|-------------|-------------------|
| Wraps the lock | Wraps NetworkManager |
| Protects the mechanism | Kill switch protects against leaks |
| Doesn't replace anything | Works alongside your existing tools |
| Hardens against attack | Hardens against failures and stale state |
The name works on three levels:
1. **Concealment** -- a VPN shrouds your traffic
2. **Hardware** -- protective armor around the lock
3. **Architecture** -- we wrap existing tools, we don't replace them
---
## The Philosophy
Most VPN tools want to own your system. They install kernel modules, replace your DNS, spawn seventeen daemons, and phone home to tell someone you're using them.
VPN Shroud doesn't do any of that.
**We wrap, we don't replace.** NetworkManager already knows how to connect to VPNs. OpenVPN and WireGuard already work. We're not here to reinvent the wheel. We're here to put armor around it.
**We fail loud, recover quiet.** When something breaks, you'll know. When it heals, you won't need to lift a finger.
**We leave no trace.** When VPN Shroud stops, your system is exactly as it was. No orphaned firewall rules. No zombie processes. No "please run this cleanup script to fix your networking."
**We respect your privacy.** No telemetry. No analytics. No phoning home. If you want to run VPN Shroud in a bunker with nothing but a VPN tunnel to the outside world, that's your right.
Read the full [Principles](docs/PRINCIPLES.md) if you want to understand what we're about.
---
## How It Gets Built
I chose Rust because the compiler enforces the kind of promises security tools need to keep. I built VPN Shroud with AI. I'm not going to pretend otherwise, because pretending would violate the same principles this tool is built on.
I broke the code, found the bugs, and fixed them. Every decision is in the [CHANGELOG](CHANGELOG.md). That's where the real work lives.
---
## What You Get
```
┌──────────────────────────────────────────────────────────────────┐
│ │
│ ✓ Kill switch that actually works │
│ └─ Traffic blocked when VPN drops. No leaks. │
│ │
│ ✓ Auto-reconnect that doesn't nag │
│ └─ Falls, gets back up, doesn't complain about it. │
│ │
│ ✓ LAN access while connected │
│ └─ Print, share files, access local devices. VPN stays up. │
│ │
│ ✓ System tray that stays out of your way │
│ └─ Click to connect. Click to disconnect. That's it. │
│ │
│ ✓ Works with any VPN provider │
│ └─ Mullvad, Nord, Proton, self-hosted, corporate. All good. │
│ │
│ ✓ Headless mode for servers │
│ └─ No GUI? No problem. Systemd integration included. │
│ │
│ ✓ Single binary, single purpose │
│ └─ One executable. CLI and daemon in one. │
│ │
└──────────────────────────────────────────────────────────────────┘
```
---
## Why VPN Shroud is Fast
- One lean Rust binary. No Electron, no heavyweight GUI stack.
- No provider handshake. We talk straight to NetworkManager with your OpenVPN/WireGuard profiles.
- Minimal background daemons. A single supervisor, no telemetry or auto-updaters.
- Tight event loop. Async Tokio + formal state machine keep connect/disconnect on the hot path.
- In-process kill switch. iptables/nft rules applied/cleaned without extra helpers.
Boot-to-VPN in ~2-4s after network is ready (with `auto_connect = true` + headless/systemd autostart).
---
## The Interface
A system tray icon that stays out of your way. Left-click for the menu. That's it.
---
## Quick Start
```bash
git clone https://github.com/lousclues-labs/shroud.git
cd shroud
./setup.sh
```
That's it. The script handles dependencies, builds the binary, installs it, sets up your desktop entry, and configures shell completions.
Then import a VPN and go:
```bash
shroud import ~/my-vpn.ovpn
shroud connect my-vpn
shroud ks on
```
You're protected.
---
## The Basics
### Starting VPN Shroud
```bash
shroud # Start with system tray
shroud --headless # Start without GUI (for servers)
shroud autostart on # Launch on login
```
### Connecting
```bash
shroud list # See your VPNs
shroud connect ireland-42 # Connect
shroud disconnect # Disconnect
shroud switch us-west-2 # Atomic switch to different VPN
shroud status # What's happening?
```
### The Kill Switch
The kill switch blocks all traffic when your VPN drops. No exceptions. No leaks.
```bash
shroud ks on # Enable
shroud ks off # Disable
shroud ks status # Check
```
When enabled, only these paths are allowed:
- Loopback (localhost)
- Your VPN tunnel
- Your local network (so you can still print)
- DHCP (so you can still get an IP)
Everything else gets dropped. DNS goes through the tunnel or nowhere.
### Importing Configs
Bring your own configs. We don't care who your provider is.
```bash
shroud import ~/mullvad-us1.conf # WireGuard
shroud import ~/corporate.ovpn --name "Work" # OpenVPN with custom name
shroud import ~/vpn-configs/ # Whole directory
shroud import ~/vpn.conf --connect # Import and connect immediately
```
---
## Documentation
| Document | What's Inside |
|----------|---------------|
| [Installation](docs/INSTALL.md) | Dependencies, building, setup |
| [CLI Reference](docs/CLI.md) | Every command, every flag |
| [Configuration](docs/CONFIGURATION.md) | The config file explained |
| [Kill Switch](docs/KILLSWITCH.md) | How the firewall rules work |
| [Headless Mode](docs/HEADLESS.md) | Running on servers |
| [Troubleshooting](docs/TROUBLESHOOTING.md) | When things go wrong |
| [Architecture](docs/ARCHITECTURE.md) | How it's built |
| [Principles](docs/PRINCIPLES.md) | Why it's built this way |
| [Contributing](CONTRIBUTING.md) | How to help |
---
## Configuration
VPN Shroud keeps its config in `~/.config/shroud/config.toml`. Here's what matters:
```toml
auto_reconnect = true # Get back up when you fall
kill_switch_enabled = false # Flip to true for always-on protection
dns_mode = "tunnel" # DNS through VPN only
ipv6_mode = "block" # Block IPv6 leaks
```
See [Configuration](docs/CONFIGURATION.md) for the full reference.
---
## The State Machine
VPN Shroud knows exactly what state it's in at all times. No guessing. No "it says connected but nothing works."
```
Disconnected ──────► Connecting ──────► Connected
▲ │ │
│ │ │
│ ▼ ▼
│ Failed Degraded
│ │ │
│ │ │
└────────────────────┴────► Reconnecting
```
Every transition is logged. Every state is real. If VPN Shroud says you're connected, you're connected.
---
## Troubleshooting
### Tray icon missing?
Your desktop needs StatusNotifierItem support. GNOME users need the [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/).
### Kill switch won't enable?
```bash
shroud doctor # Run diagnostics
./setup.sh --install-sudoers # Install the sudoers rule
```
### Stuck with no internet?
If VPN Shroud crashes with the kill switch on:
```bash
shroud ks off # Try this first
# If Shroud isn't responding:
sudo iptables -D OUTPUT -j SHROUD_KILLSWITCH
sudo iptables -F SHROUD_KILLSWITCH
sudo iptables -X SHROUD_KILLSWITCH
```
### Debug mode
```bash
shroud debug on # Start logging everything
shroud debug tail # Watch the logs
```
See [Troubleshooting](docs/TROUBLESHOOTING.md) for more.
---
## Installation
### From lousclues packages
Once the first release is published, this project will be installable
via the lousclues package repository. See the install instructions at
.
```bash
# Ubuntu/Debian:
sudo apt install shroud
# RHEL/Fedora:
sudo dnf install shroud
```
## Contributing
Contributions are welcome. But first, read the [Principles](docs/PRINCIPLES.md). Every contribution should align with them.
The short version:
- Wrap, don't replace
- Fail loud, recover quiet
- Leave no trace
- Keep it simple
See [Contributing](CONTRIBUTING.md) for the full guide.
---
## Requirements
- Linux (Arch, Debian, Ubuntu, Fedora, etc.)
- NetworkManager with OpenVPN and/or WireGuard plugins
- iptables or nftables
- A VPN config file
That's really it.
---
## License
Copyright (C) 2026 **Louis Nelson Jr.** -- a [lousclues](https://lousclues.com) project.
VPN Shroud is dual-licensed:
| Component | License | File |
|-----------|---------|------|
| Source Code | GNU GPL v3.0 or later **or** Commercial License | [LICENSE](LICENSE), [LICENSE-COMMERCIAL.md](licenses/LICENSE-COMMERCIAL.md) |
| Documentation | Creative Commons Attribution 4.0 (CC BY 4.0) | [LICENSE-DOCS.md](licenses/LICENSE-DOCS.md) |
| Third-Party Dependencies | MIT, Apache-2.0, and other permissive licenses | [THIRD-PARTY-LICENSES](licenses/THIRD-PARTY-LICENSES) |
**For most users:** The GPL covers you fully. Use VPN Shroud, connect your VPNs, run the daemon. No restrictions beyond the GPL.
**For proprietary/commercial use:** If you need to embed VPN Shroud in closed-source products or redistribute without GPL obligations, a [commercial license](licenses/LICENSE-COMMERCIAL.md) is available.
**For contributors:** By submitting a pull request, you agree to the [Contributor License Agreement](licenses/CONTRIBUTOR-LICENSE.md). You keep your copyright; you grant the project permission to include your contribution under both licenses.
**Trademarks:** "VPN Shroud" is the composite project name and is not a claim of rights over "VPN" or "Shroud" individually. "lousclues" is a trademark of Louis Nelson Jr. See [TRADEMARKS.md](TRADEMARKS.md) for usage guidelines. The GPL does not grant trademark rights.
For the complete licensing framework, see [LICENSING.md](licenses/LICENSING.md). For project governance and succession planning, see [GOVERNANCE.md](GOVERNANCE.md).
---
*VPN Shroud: Wrap your VPN in armor, not bloatware.*
*We protect. We recover. We disappear.*
*Your traffic is your business.*