@dsh-operatingtag/dsh-vpn
v1.0.0
Published
A Windows 11 style VPN control panel for DeepSeek Harness: Proton browser sign-in, geolocation-ranked WireGuard servers, automatic configuration, leak-proof kill switch, one-click restore.
Maintainers
Readme
dsh-vpn
A Windows 11-style VPN control panel for DeepSeek Harness.
Sign in to Proton in a real browser, let the plugin rank free WireGuard servers by
your actual location and live load, generate the configuration itself, connect,
and restore the machine in one click.
Revolut Me · Apache-2.0 · Windows 10/11 x64
Unofficial project. Not affiliated with, endorsed by, or sponsored by Proton AG, DeepSeek, or the WireGuard project. See NOTICE.
English · Design and implementation · Security · Contributions are not accepted · Changelog
English · 中文 · 日本語 · Français · Deutsch · Español · Português · Русский · Italiano
If this project is useful to you, a star on GitHub is appreciated but entirely optional: github.com/operatingtag
Why this exists
DeepSeek Harness plugins can register model routes, tools, and settings pages —
but none of them manage a real VPN. dsh-vpn closes that gap with a complete,
auditable lifecycle:
- No password ever reaches the plugin. Proton's SRP login happens in a real browser window; the plugin captures only the resulting session.
- No blind server picking. The dashboard's server table is scraped, deduped, and ranked by great-circle distance from your detected position, with load breaking ties inside a distance band.
- No half-configured machine. Every system change has an inverse; Restore stops the tunnel, removes WireGuard, clears firewall rules, and keeps your saved configurations.
- No opaque install. WireGuard's MSI is downloaded from the official URL and verified against a pinned SHA-256 before it runs.
Features
| Area | What you get |
|---|---|
| Account | Sign in to Proton opens Proton's own login page. 2FA, captcha, and password stay with Proton. Sign out closes the browser and drops the session. |
| Server ranking | Geolocation from public IP, timezone fallback, country-centre distance, load tie-break inside a 1.3× band. |
| Automatic setup | After sign-in the plugin picks the nearest least-loaded server without a config and creates its .conf through the dashboard. |
| Tunnel lifecycle | Install WireGuard (pinned MSI), install the tunnel service, verify the handshake, switch servers, stop cleanly. |
| Kill switch | Windows Firewall default outbound Block plus four allow rules: tunnel interface, VPN endpoint, loopback, DHCP. Transactional: a partial apply rolls back. |
| Restore | One click: stop tunnel, uninstall WireGuard, remove firewall rules, clear state. Configurations are preserved. |
| Admin panel | Three placements: the plugin's own detail page (above the README), a VPN tab under Settings → Plugins, and a VPN entry in the Settings nav. |
| Panel languages | Eight follow the harness locale service; Italiano is panel-only. |
| Tools & commands | Four agent tools and six slash commands for scripted use. |
Requirements
- Windows 10 or 11, x64
- DeepSeek Harness running elevated (Administrator)
- Node 20+ (the harness bundles one)
- A free Proton VPN account for the browser sign-in path
A plugin cannot raise a UAC prompt for the harness it runs inside. Every
mutating action checks the token and fails with NOT_ELEVATED when the harness
is not elevated. Nothing is installed silently.
Install
From npm, in your harness profile directory:
pnpm add @dsh-operatingtag/dsh-vpnThen enable the bundle in Settings → Plugins and refresh the GUI (Ctrl+R).
Or from a session in the harness:
Install the DSH bundle at <absolute path to this folder>
and confirm the plugin row include:vpn is active.Or by hand:
- Copy this folder somewhere permanent.
- Add
"dsh-vpn": "link:C:/path/to/this/folder"to the profile'sdependenciesand"dsh-vpn"todsh.profile.bundles. - Run
pnpm installin the profile directory. - Restart the harness.
Enable the bundle in Settings → Plugins, then refresh the GUI (Ctrl+R).
Quick start
- Settings → Plugins → VPN (or the dsh-vpn detail page).
- Sign in to Proton — a browser window opens; complete the login there.
- Wait for the panel to report Signed in. The plugin scrapes the server list, picks the nearest least-loaded server without a configuration, and creates it. That row now shows Switch.
- Switch — WireGuard installs if missing, the tunnel starts, the handshake appears, and the switch flips on.
- Optional: toggle Kill switch.
- Restore system when you want the machine back to stock. Configs remain.
Architecture
┌───────────────────────────── Browser (harness UI) ─────────────────────────────┐
│ client.js ── Settings page + Plugins tab + detail section │
│ │ fetch /api/dsh-vpn/* (same-origin + per-process token) │
└───┼────────────────────────────────────────────────────────────────────────────┘
│
┌───▼──────────────────────────── Host (Node, elevated) ─────────────────────────┐
│ index.js ── tools, commands, panel route, auto-connect │
│ ├─ lib/panel.mjs HTTP actions, token, status projection │
│ ├─ lib/proton.mjs browser sign-in, session, scrape, config generation │
│ ├─ lib/browser.mjs CDP client, browser launch/stop, download suppression │
│ ├─ lib/geo.mjs location detection, distance band, choice │
│ ├─ lib/servers.mjs snapshot store, validation, dedupe, ranking │
│ ├─ lib/admin.mjs WireGuard install/verify, sc.exe tunnel control │
│ ├─ lib/killswitch.mjs firewall rules, transactional apply/rollback │
│ ├─ lib/restore.mjs full system restore │
│ ├─ lib/config.mjs paths, config, state, system marker │
│ └─ lib/i18n.mjs locale catalogs, runtime translator │
│ │
│ Windows: WireGuard MSI · Wintun tunnel service · Windows Firewall │
└────────────────────────────────────────────────────────────────────────────────┘A deeper treatment — algorithms, state machines, test matrix, threat model — is in docs/design-paper.md.
How the interesting parts work
Location → server choice
- Public-IP geolocation (
ipwho.is) →lat,lon, country, city. Fallback: OS timezone → country centre. Fallback: Netherlands. - Great-circle distance to each server country's centre.
band = max(nearest × 1.3, nearest + 250 km).- Servers inside the band compete on load; the rest stay ordered by distance. Unconfigured servers win over already-configured ones.
From Madrid this selects a 66–70 % Dutch server over an 82 % Swiss one, while never letting a 5 % US server win on load.
Sign-in without touching the password
The plugin launches Edge/Chrome with a throwaway profile and remote debugging.
The user signs in on Proton's page. The plugin polls location.href until it
leaves /login, then reads cookies via CDP — never form values, never the
password. The profile is deleted on sign-out.
Config generation without a duplicate download
The dashboard's Create button both fills a textarea and starts a file
download. The plugin sets Page.setDownloadBehavior: deny first, clicks Create,
and reads only the textarea. No stray .conf lands in Downloads.
Tunnel control without PowerShell
Service state is read with sc.exe query and the numeric SCM state
(4 = RUNNING), which is language-independent. Measured on the development
machine: 44 ms versus 1425 ms for Get-Service — a 32× improvement.
Kill switch
Enabling sets DefaultOutboundAction = Block for Domain, Private, and Public,
then adds allow rules for the tunnel interface, the endpoint IP/port, IPv4
loopback, and DHCP. The apply verifies four rules and Block; any failure
removes the rules and restores Allow before reporting. Verified by stopping the
tunnel: curl fails with exit 7, so no traffic leaks.
Restore
restoreSystem() signs out, clears firewall rules, stops and removes the tunnel
service, uninstalls WireGuard, deletes runtime state, and keeps every
.conf. Exit IP returns to the ISP address.
Tools
| Tool | Purpose |
|---|---|
| vpn_status | Elevation, WireGuard, tunnel, handshake, recommended server |
| vpn_setup | Install WireGuard and activate a .conf; plan without confirm |
| vpn_switch | Switch configuration; plan without confirm |
| vpn_servers | Rank or import the free-server snapshot |
Commands
| Command | Purpose |
|---|---|
| /vpn | Human-readable status |
| /vpn-setup <path> | Activate a configuration |
| /vpn-switch <path> | Switch configuration |
| /vpn-off | Stop the tunnel |
| /vpn-servers | Rank servers |
| /vpn-servers-import <path> | Import a server snapshot |
Languages
English, 中文, 日本語, Français, Deutsch, Español, Português, Русский.
The panel also ships Italiano. Italian is panel-only: the Harness interface does not offer it, so the panel manages that choice itself and the rest of the Harness stays in its own language. The language selector is in the panel; no Harness setting is changed.
locales/en.json is the master. scripts/i18n.mjs keeps a hash per key, so a
release only translates what changed:
node scripts/i18n.mjs status
node scripts/i18n.mjs sync --accept
node scripts/i18n.mjs packet de
node scripts/i18n.mjs merge de locales/.packets/de.json
node scripts/i18n.mjs check
node scripts/build-client.mjsTool descriptions stay English because they are model-facing. Everything a person reads — commands, status, errors, panel — is translated.
Data and security
| Path | Contents |
|---|---|
| %LOCALAPPDATA%\dsh-vpn\*.conf | WireGuard configurations, private keys, ACL: user + SYSTEM |
| %LOCALAPPDATA%\dsh-vpn\servers.json | Last server snapshot |
| %LOCALAPPDATA%\dsh-vpn\state.json | Active/selected tunnel |
| %LOCALAPPDATA%\dsh-vpn\system.json | Marker for changes the plugin made |
- Proton password never leaves Proton's page.
- Panel API: per-process token and same-origin/loopback check.
- WireGuard MSI: pinned URL + SHA-256, verified before execution.
- Kill switch off by default; cleared by Restore.
- Config files grant SYSTEM read so the tunnel service can start.
Development
node scripts/selftest.mjs # preflight, geo, i18n, service control
node scripts/i18n.mjs check # translation completeness
node scripts/build-client.mjs # rebuild the panel bundle
node scripts/pow-selftest.mjs # (webchat plugin only)Testing notes, measured numbers, and the verification matrix are in docs/design-paper.md.
Roadmap
- [ ] Split tunnelling (
AllowedIPsprofiles) - [ ] Panel toggle for auto-connect and kill-switch defaults
- [ ] IKEv2 path for Windows Settings integration
- [ ] GitHub Pages documentation in all eight languages
- [ ] Signed MSIX wrapper for non-harness users
Support the work
dsh-vpn is free, Apache-2.0, and maintained by one person. There is no company,
no telemetry, and no subscription.
If it saves you time, you can support its continued development with a one-off donation through Revolut Me, or read the full funding story — what donations pay for, and what they explicitly do not buy — in FUNDING.md.
A star on GitHub is appreciated but entirely optional: https://github.com/operatingtag/dsh-vpn
License
Copyright 2026 Darren Thomas Weldon. Licensed under the Apache License 2.0 — see LICENSE and NOTICE.
Security: see SECURITY.md for the threat model and known
limitations. Report vulnerabilities privately to [email protected].
Contributions are not accepted. This is not a collaboration. See
CONTRIBUTING.md. The [email protected] address is for
business enquiries only.
Third-party notices
- WireGuard for Windows — Copyright (C) 2015–2026 Jason A. Donenfeld, MIT licence. Distributed by WireGuard; this project downloads the official installer and verifies its hash, and does not bundle it.
- Proton VPN — protonvpn.com. Proton and Proton VPN are trademarks of Proton AG. This project is unofficial and is not affiliated with or endorsed by Proton AG; use is subject to Proton's own terms.
- DeepSeek Harness — DeepSeek and DeepSeek Harness are trademarks of their respective owners. This plugin is independent and unofficial.
