{"id":49760007,"url":"https://github.com/lousclues-labs/shroud","last_synced_at":"2026-05-25T07:01:12.334Z","repository":{"id":341327554,"uuid":"1137208075","full_name":"lousclues-labs/shroud","owner":"lousclues-labs","description":"A provider-agnostic VPN connection manager for Linux: kill switch, auto-reconnect, system tray, zero telemetry.","archived":false,"fork":false,"pushed_at":"2026-05-24T01:24:12.000Z","size":2059,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-24T03:13:05.225Z","etag":null,"topics":["kill-switch","linux","network-manager","openvpn","privacy","system-tray","vpn","wireguard"],"latest_commit_sha":null,"homepage":"https://vpnshroud.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lousclues-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-19T04:12:12.000Z","updated_at":"2026-05-24T01:24:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lousclues-labs/shroud","commit_stats":null,"previous_names":["loujr/shroud","loujr/vpnshroud","lousclues-labs/shroud"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/lousclues-labs/shroud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lousclues-labs%2Fshroud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lousclues-labs%2Fshroud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lousclues-labs%2Fshroud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lousclues-labs%2Fshroud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lousclues-labs","download_url":"https://codeload.github.com/lousclues-labs/shroud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lousclues-labs%2Fshroud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33464012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kill-switch","linux","network-manager","openvpn","privacy","system-tray","vpn","wireguard"],"created_at":"2026-05-11T04:31:10.377Z","updated_at":"2026-05-25T07:01:12.321Z","avatar_url":"https://github.com/lousclues-labs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VPN Shroud\n\n[![CI](https://github.com/lousclues-labs/shroud/actions/workflows/ci.yml/badge.svg)](https://github.com/lousclues-labs/shroud/actions/workflows/ci.yml)\n[![Security Audit](https://github.com/lousclues-labs/shroud/actions/workflows/scheduled.yml/badge.svg)](https://github.com/lousclues-labs/shroud/actions/workflows/scheduled.yml)\n[![Version](https://img.shields.io/badge/version-2.2.0-blue)](CHANGELOG.md)\n[![Rust](https://img.shields.io/badge/rust-1.87%2B-orange.svg)](https://www.rust-lang.org/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)\n\n**A provider-agnostic VPN connection manager for Linux.**\n\nA **lock shroud** is the protective metal casing around a padlock's shackle. It doesn't replace the lock. It protects the lock from attack.\n\n```\n┌─────────────────────────────────────────┐\n│                                         │\n│         ┌───────────┐                   │\n│         │  SHROUD   │ ← Protective      │\n│         │ ┌───────┐ │    outer casing   │\n│         │ │ LOCK  │ │                   │\n│         │ │MECHANISM│ ← The vulnerable  │\n│         │ └───────┘ │    internals      │\n│         └───────────┘                   │\n│                                         │\n└─────────────────────────────────────────┘\n```\n\nThat's what VPN Shroud does:\n\n| Lock Shroud | VPN Shroud (This Tool) |\n|-------------|-------------------|\n| Wraps the lock | Wraps NetworkManager |\n| Protects the mechanism | Kill switch protects against leaks |\n| Doesn't replace anything | Works alongside your existing tools |\n| Hardens against attack | Hardens against failures and stale state |\n\nThe name works on three levels:\n1. **Concealment** -- a VPN shrouds your traffic\n2. **Hardware** -- protective armor around the lock\n3. **Architecture** -- we wrap existing tools, we don't replace them\n\n---\n\n## The Philosophy\n\nMost 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.\n\nVPN Shroud doesn't do any of that.\n\n**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.\n\n**We fail loud, recover quiet.** When something breaks, you'll know. When it heals, you won't need to lift a finger.\n\n**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.\"\n\n**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.\n\nRead the full [Principles](docs/PRINCIPLES.md) if you want to understand what we're about.\n\n---\n\n## How It Gets Built\n\nI 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.\n\nI broke the code, found the bugs, and fixed them. Every decision is in the [CHANGELOG](CHANGELOG.md). That's where the real work lives.\n\n---\n\n## What You Get\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                                                                  │\n│   ✓ Kill switch that actually works                              │\n│     └─ Traffic blocked when VPN drops. No leaks.                 │\n│                                                                  │\n│   ✓ Auto-reconnect that doesn't nag                              │\n│     └─ Falls, gets back up, doesn't complain about it.           │\n│                                                                  │\n│   ✓ LAN access while connected                                   │\n│     └─ Print, share files, access local devices. VPN stays up.   │\n│                                                                  │\n│   ✓ System tray that stays out of your way                       │\n│     └─ Click to connect. Click to disconnect. That's it.         │\n│                                                                  │\n│   ✓ Works with any VPN provider                                  │\n│     └─ Mullvad, Nord, Proton, self-hosted, corporate. All good.  │\n│                                                                  │\n│   ✓ Headless mode for servers                                    │\n│     └─ No GUI? No problem. Systemd integration included.         │\n│                                                                  │\n│   ✓ Single binary, single purpose                                │\n│     └─ One executable. CLI and daemon in one.                    │\n│                                                                  │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Why VPN Shroud is Fast\n- One lean Rust binary. No Electron, no heavyweight GUI stack.\n- No provider handshake. We talk straight to NetworkManager with your OpenVPN/WireGuard profiles.\n- Minimal background daemons. A single supervisor, no telemetry or auto-updaters.\n- Tight event loop. Async Tokio + formal state machine keep connect/disconnect on the hot path.\n- In-process kill switch. iptables/nft rules applied/cleaned without extra helpers.\n\nBoot-to-VPN in ~2-4s after network is ready (with `auto_connect = true` + headless/systemd autostart).\n\n---\n\n## The Interface\n\nA system tray icon that stays out of your way. Left-click for the menu. That's it.\n\n\u003cimg width=\"306\" height=\"569\" alt=\"shroud3\" src=\"https://github.com/user-attachments/assets/d5c5603a-153e-4d96-9ef9-7a4170b51f1c\" /\u003e\n\n\n---\n\n## Quick Start\n\n```bash\ngit clone https://github.com/lousclues-labs/shroud.git\ncd shroud\n./setup.sh\n```\n\nThat's it. The script handles dependencies, builds the binary, installs it, sets up your desktop entry, and configures shell completions.\n\nThen import a VPN and go:\n\n```bash\nshroud import ~/my-vpn.ovpn\nshroud connect my-vpn\nshroud ks on\n```\n\nYou're protected.\n\n---\n\n## The Basics\n\n### Starting VPN Shroud\n\n```bash\nshroud                    # Start with system tray\nshroud --headless         # Start without GUI (for servers)\nshroud autostart on       # Launch on login\n```\n\n### Connecting\n\n```bash\nshroud list               # See your VPNs\nshroud connect ireland-42 # Connect\nshroud disconnect         # Disconnect\nshroud switch us-west-2   # Atomic switch to different VPN\nshroud status             # What's happening?\n```\n\n### The Kill Switch\n\nThe kill switch blocks all traffic when your VPN drops. No exceptions. No leaks.\n\n```bash\nshroud ks on              # Enable\nshroud ks off             # Disable\nshroud ks status          # Check\n```\n\nWhen enabled, only these paths are allowed:\n- Loopback (localhost)\n- Your VPN tunnel\n- Your local network (so you can still print)\n- DHCP (so you can still get an IP)\n\nEverything else gets dropped. DNS goes through the tunnel or nowhere.\n\n### Importing Configs\n\nBring your own configs. We don't care who your provider is.\n\n```bash\nshroud import ~/mullvad-us1.conf              # WireGuard\nshroud import ~/corporate.ovpn --name \"Work\"  # OpenVPN with custom name\nshroud import ~/vpn-configs/                   # Whole directory\nshroud import ~/vpn.conf --connect             # Import and connect immediately\n```\n\n---\n\n## Documentation\n\n| Document | What's Inside |\n|----------|---------------|\n| [Installation](docs/INSTALL.md) | Dependencies, building, setup |\n| [CLI Reference](docs/CLI.md) | Every command, every flag |\n| [Configuration](docs/CONFIGURATION.md) | The config file explained |\n| [Kill Switch](docs/KILLSWITCH.md) | How the firewall rules work |\n| [Headless Mode](docs/HEADLESS.md) | Running on servers |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | When things go wrong |\n| [Architecture](docs/ARCHITECTURE.md) | How it's built |\n| [Principles](docs/PRINCIPLES.md) | Why it's built this way |\n| [Contributing](CONTRIBUTING.md) | How to help |\n\n---\n\n## Configuration\n\nVPN Shroud keeps its config in `~/.config/shroud/config.toml`. Here's what matters:\n\n```toml\nauto_reconnect = true              # Get back up when you fall\nkill_switch_enabled = false        # Flip to true for always-on protection\ndns_mode = \"tunnel\"                # DNS through VPN only\nipv6_mode = \"block\"                # Block IPv6 leaks\n```\n\nSee [Configuration](docs/CONFIGURATION.md) for the full reference.\n\n---\n\n## The State Machine\n\nVPN Shroud knows exactly what state it's in at all times. No guessing. No \"it says connected but nothing works.\"\n\n```\n    Disconnected ──────► Connecting ──────► Connected\n         ▲                    │                 │\n         │                    │                 │\n         │                    ▼                 ▼\n         │                 Failed           Degraded\n         │                    │                 │\n         │                    │                 │\n         └────────────────────┴────► Reconnecting\n```\n\nEvery transition is logged. Every state is real. If VPN Shroud says you're connected, you're connected.\n\n---\n\n## Troubleshooting\n\n### Tray icon missing?\n\nYour desktop needs StatusNotifierItem support. GNOME users need the [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/).\n\n### Kill switch won't enable?\n\n```bash\nshroud doctor              # Run diagnostics\n./setup.sh --install-sudoers  # Install the sudoers rule\n```\n\n### Stuck with no internet?\n\nIf VPN Shroud crashes with the kill switch on:\n\n```bash\nshroud ks off              # Try this first\n\n# If Shroud isn't responding:\nsudo iptables -D OUTPUT -j SHROUD_KILLSWITCH\nsudo iptables -F SHROUD_KILLSWITCH\nsudo iptables -X SHROUD_KILLSWITCH\n```\n\n### Debug mode\n\n```bash\nshroud debug on            # Start logging everything\nshroud debug tail          # Watch the logs\n```\n\nSee [Troubleshooting](docs/TROUBLESHOOTING.md) for more.\n\n---\n\n## Installation\n\n### From lousclues packages\n\nOnce the first release is published, this project will be installable\nvia the lousclues package repository. See the install instructions at\n\u003chttps://pkg.lousclues.com/install/\u003e.\n\n```bash\n# Ubuntu/Debian:\nsudo apt install shroud\n\n# RHEL/Fedora:\nsudo dnf install shroud\n```\n\n## Contributing\n\nContributions are welcome. But first, read the [Principles](docs/PRINCIPLES.md). Every contribution should align with them.\n\nThe short version:\n- Wrap, don't replace\n- Fail loud, recover quiet  \n- Leave no trace\n- Keep it simple\n\nSee [Contributing](CONTRIBUTING.md) for the full guide.\n\n---\n\n## Requirements\n\n- Linux (Arch, Debian, Ubuntu, Fedora, etc.)\n- NetworkManager with OpenVPN and/or WireGuard plugins\n- iptables or nftables\n- A VPN config file\n\nThat's really it.\n\n---\n\n## License\n\nCopyright (C) 2026 **Louis Nelson Jr.** -- a [lousclues](https://lousclues.com) project.\n\nVPN Shroud is dual-licensed:\n\n| Component | License | File |\n|-----------|---------|------|\n| Source Code | GNU GPL v3.0 or later **or** Commercial License | [LICENSE](LICENSE), [LICENSE-COMMERCIAL.md](licenses/LICENSE-COMMERCIAL.md) |\n| Documentation | Creative Commons Attribution 4.0 (CC BY 4.0) | [LICENSE-DOCS.md](licenses/LICENSE-DOCS.md) |\n| Third-Party Dependencies | MIT, Apache-2.0, and other permissive licenses | [THIRD-PARTY-LICENSES](licenses/THIRD-PARTY-LICENSES) |\n\n**For most users:** The GPL covers you fully. Use VPN Shroud, connect your VPNs, run the daemon. No restrictions beyond the GPL.\n\n**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.\n\n**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.\n\n**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.\n\nFor the complete licensing framework, see [LICENSING.md](licenses/LICENSING.md). For project governance and succession planning, see [GOVERNANCE.md](GOVERNANCE.md).\n\n---\n\n*VPN Shroud: Wrap your VPN in armor, not bloatware.*\n\n*We protect. We recover. We disappear.*\n\n*Your traffic is your business.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flousclues-labs%2Fshroud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flousclues-labs%2Fshroud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flousclues-labs%2Fshroud/lists"}