dsh-lan-guard
DSH web plugin: expose the official desktop Web UI to the local network through a gated reverse proxy, without touching DSH's own loopback binding.
安裝
npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-lan-guard@latest說明文件
閱讀完整 README ↗DSH LAN Guard
Expose the desktop DSH Web UI to your LAN safely: a gated reverse proxy with self-signed HTTPS by default and a QR code to open it on a phone. DSH's own loopback binding and the official UI stay untouched.
English | 中文
What it does · Quick start · Settings · Compatibility · Security boundary · Troubleshooting · Changelog
DSH LAN Guard is a DeepSeek Harness community plugin. It registers one section in the official settings page (
settings.section), replaces no official layout, and modifies neither DSH source nor DSH's own listen binding.
DSH serves its Web UI on 127.0.0.1 only, and it deliberately refuses to bind 0.0.0.0. This plugin leaves that binding alone and opens a second, gated listener on another port, proxying the official UI outward as-is: a password gate, self-signed HTTPS by default, a QR code to open it on a phone, and device pairing you can approve or block one by one. One restart after install is all it takes — no hand-written configuration.

What it does
- Gated reverse proxy — relays HTTP and WebSocket end to end (including the official UI's
/api/remote.muxlong connection), rewritesHost/Origin, strips hop-by-hop headers, and answers502when the upstream is down. DSH's own binding and configuration are never touched. - LAN-ready by default, but reachable is not the same as enterable — it binds
0.0.0.0, so one restart after install is enough. The gate is on by default and refuses every device until you set an access password, and TLS is self-signed by default — nothing travels in clear. Switch to "this machine only" in the settings page if you prefer. - Two passwords — PBKDF2-SHA256 (600,000 iterations). The access password logs visitor devices in; the admin password unlocks this settings page's management console (it falls back to the access password). Plus a
dsh_passwordless link, persistent visitor sessions, per-IP lockout and CSRF checks. - Self-signed HTTPS by default, with a stable CA — generates a
DSH LAN Guard CAand signs a leaf certificate for the current NIC addresses. Changing IP only re-signs the leaf, so each device trusts the CA once. - Your own machine is never locked — direct
127.0.0.1access is physically unlocked (whoever can use this computer could change these settings anyway). Remote access followsadminPolicy: read-only (default), password-unlocked, or open. - Device pairing and credential blocking — a phone names itself once when it first passes the gate, receives an HttpOnly device-identity cookie, and appears under 已授权设备 (name / created / last used / source IP) where you can revoke or block that identity. The block persists for the recorded identity, not the physical machine: a fresh browser or cleared cookie can pair again with the shared access password. Enable approval for new devices when you need to review re-pairing.
- Settings inside the official page — the "局域网访问" section has four tabs: QR access, authentication, authorised devices, and connection & certificates. All typography and colours use the official design tokens; no official layout is replaced.
- Adding a workspace from a phone (smart routing) — DSH resolves its directory picker once at boot, and a loopback bind with a display resolves to
native: tapping "添加工作区" on a phone actually opens the folder dialog on the host's screen. This plugin shadows the official pick flow from the browser half at a lower slot priority, so the local browser keeps the OS dialog while a remote device gets an in-page directory browser (breadcrumbs, shortcuts, directory list). The chosen path still goes through DSH's own workspace flow — this plugin only reads directories, never writes anything. - Configurable port and listen scope — defaults to
3081(DSH's port + 1) and walks up to ten ports when that one is taken, with an availability check in the settings page. The listen scope toggles between "LAN (default)" and "this machine only"; both need a DSH restart. - Optional mDNS — off by default; advertises
_dsh-lan-guard._tcpwhen enabled. - Update check — the settings page shows "current version → latest on npm" with a copyable upgrade command. The plugin never installs or restarts anything itself.
Quick start
Requirements:
- DeepSeek Harness with a Web profile
- Node.js 20 or newer
- Verified DeepSeek Harness:
0.2.2-rc.3(API review, current dependency type checks and automated regression; read-only checks on the running rc.3 instance confirm the proxy entry, page-patch injection, client module and management endpoints.0.2.2-rc.2host builds and types are byte-identical to rc.3, so it is listed as verified too. Browser interaction, full LAN/WebSocket and phone acceptance have not been repeated for rc.3; the alpha.3 browser measurements belong to an earlier release). - Registry channels checked on 2026-11-14:
next=0.2.2-rc.3,latest=0.2.2-rc.1,alpha=0.2.2-alpha.3. This release verifies0.2.2-rc.3(and0.2.2-rc.2);0.2.2-rc.1on thelatestchannel belongs to the previous release's verification scope.
Install from npm:
dsh plugin --profile web add dsh-lan-guard@latest
Install from GitHub:
dsh plugin --profile web add "github:idoall/dsh-lan-guard"
Install from a local clone:
git clone https://github.com/idoall/dsh-lan-guard.git
cd dsh-lan-guard
pnpm install && pnpm run build
dsh plugin --profile web add "link:$(pwd)"
Then restart DSH once and open Settings → 局域网访问. After that restart the plugin is already listening on the LAN (default 0.0.0.0:3081, self-signed HTTPS + gate); all you do is:
- Set an access password (at least 8 characters) under 安全认证. Until you do, the gate refuses every device.
- Check the listen scope under 连接与证书 (LAN by default) and pick the NIC to publish on — the NIC decides which IP the QR code / access URL uses and which addresses the self-signed certificate covers.
- Scan the QR under 扫码访问, trust
DSH LAN Guard CAonce on the phone, enter the access password, and name the device. The phone then runs the official DSH UI.
Remote devices are read-only by default (
adminPolicy: local_only): they can use DSH but cannot change plugin settings. Switch the policy on the desktop if you want a phone to manage them.
Settings
Everything lives under Settings → 局域网访问, in four tabs. The non-sensitive switches (enabled, listenPort, listenHost, networkInterface, settingsUnlock, answerHeartbeat, socketWatchdog, mobileCompat, mobileScrollFix, mobileTurnRail, auth.mode, auth.adminPolicy, auth.adminProtection, auth.allowLoopback, auth.requirePairing, auth.requireApproval) are editable directly; listenPort and listenHost take effect on the next DSH restart; settingsUnlock, socketWatchdog, mobileCompat, mobileScrollFix and mobileTurnRail take effect on the next page load while answerHeartbeat also applies to connections that are already open; dataDir and tls.* are startup fields that need a profile-patch edit.
| Setting | Default | Effect |
|---|---|---|
| Listen scope | LAN 0.0.0.0 | Whether the LAN can reach the port. "This machine only 127.0.0.1" is more conservative; needs a DSH restart. Both choices keep the gate and self-signed HTTPS in force. |
| Proxy port | 3081 | DSH's port + 1; walks up to ten ports when taken, with an availability check. Needs a DSH restart. |
| NIC to publish on | automatic | Decides which IP the QR code / access URL uses and which addresses the certificate covers; virtual NICs are de-prioritised and labelled. |
| Auth mode | passwordless QR + password | Also "password only" or "secure token only". Switching revokes every existing visitor session. |
| Access password | unset | The login password for visitor devices. While unset, the gate refuses every device. |
| Admin password | unset | Unlocks this settings page's management console; falls back to the access password. |
| Loopback exempt | on | Direct 127.0.0.1 access skips the gate (physically unlocked). |
| Remote management rights | this machine only | Whether LAN devices may manage: "this machine only" is read-only; "password unlock" needs an unlock first; "not locked" adds no requirement. Browsing directories and adding a workspace remotely needs one of the latter two. |
| Management needs an unlock | on | Turned off, a remote session that satisfies the policy may change settings directly — except under "this machine only", which never allows remote management. |
| Official settings page on the LAN | on | DSH opens its official settings surface only to loopback pages, so a LAN device opening Settings → Models reports settings are unavailable in this browser. With this on, any device that passes the gate (phones included) can use those pages after a page refresh. It is a UI unlock, not a new privilege: the settings RPC is gated by the visitor gate either way, and DSH still redacts secret reads. Refresh the page to apply; no restart needed. |
| Answer the host heartbeat | on | DSH pings every WebSocket every 2 s and drops it after two unanswered pings (measured: 6 s). A suspended phone cannot answer, and the session transcript — the only part of the UI that rides that socket — then loads incompletely or disconnects. With this on the proxy answers instead; the phone's own Pong, when it arrives, is a harmless duplicate. Applies immediately, including to open connections. |
| Socket watchdog | on | Page patch: a WebSocket still in CONNECTING after 8 s is closed, and a page resumed with nothing open reloads itself once (at most three in a row per tab, backing off from 20 s). Only a page that genuinely cannot connect is affected. Applies on page refresh. |
| Mobile compatibility shims | on | Page patch: fills in AbortSignal.any/AbortSignal.timeout/Promise.withResolvers/Iterator and the mobile metas. Without those APIs DSH's client throws inside its session-stream path and the UI just sits on 「载入历史…」 with no error at all. On a modern engine every branch is a no-op. Applies on page refresh. |
| Narrow-screen scroll fix | on | DSH's own shell clips the conversation column on a phone (pI_x6G_frame, measured 844/1688) and the page cannot scroll, so content is visible but cannot be dragged. The patch only acts when narrow screen + mobile UA + page cannot scroll + a clipping overflowing layer exists; healthy pages are untouched. ?lgdiag=1 prints a layout report. Applies on page refresh. |
| Require naming | on | A new device must name itself once before it appears in the device list. |
| Require approval | off | When on, a named device still needs your 批准 before it is let in. |
| TLS | self-signed HTTPS | Turning it off sends the gate password in clear; a non-loopback bind with TLS off is refused at startup unless you set tls.allowInsecureLan: true. |

The plugin reads its config from its Cordis entry. Every key has a usable default, so a fresh install works as-is:
# ~/.dsh/profiles/web/cordis.patch.yml (optional: write only what you want to change)
- id: dsh-lan-guard
config:
listenHost: 0.0.0.0 # LAN-facing by default; '127.0.0.1' = this machine only, or one NIC IP
listenPort: 3081 # DSH port + 1; auto-walks up to 10 ports when taken
networkInterface: en0 # optional: publish on one NIC (empty = automatic)
settingsUnlock: true # LAN devices may use the official settings page (default on)
answerHeartbeat: true # proxy answers the WebSocket heartbeat (default on)
socketWatchdog: true # page-side socket watchdog (default on)
mobileCompat: true # mobile compatibility shims (default on)
mobileTurnRail: false # show DSH's own turn rail on narrow screens (default off)
dataDir: ~/.dsh/profiles/web/data/dsh-lan-guard # optional; this is the derived default
tls:
mode: self-signed # 'self-signed' (default) | 'provided' | 'off'
allowInsecureLan: false # required acknowledgement for LAN plain HTTP
mdns:
enabled: false # advertise _dsh-lan-guard._tcp
auth:
mode: token_and_password # 'token_and_password' | 'password' | 'token'
adminPolicy: local_only # 'local_only' (default) | 'password_unlock' | 'open'
adminProtection: true # admin console needs the admin password
allowLoopback: true # 127.0.0.1 visitors skip the gate (physically unlocked)
requirePairing: true # new remote devices must name themselves once
dataDir is the only key that needs explaining: omit it and the plugin uses /data/dsh-lan-guard (e.g. ~/.dsh/profiles/web/data/dsh-lan-guard); set it and your value wins (a leading ~ is expanded). It only decides where the plugin's private state (password hashes, device-token hashes, sessions, self-signed CA) lives — never whether the plugin works.


Compatibility
Current version: plugin 0.7.11, compatible with DeepSeek Harness 0.2.2-rc.3. Each row below is one plugin release: the DSH versions it was verified against, and what that release did.
| Plugin | Verified DeepSeek Harness | What this version is |
|---|---|---|
0.7.11 (latest) | 0.2.2-rc.3, 0.2.2-rc.2; earlier verified releases listed below | Compatibility release for rc.3: host packages (webserver / connection / scope) kept byte-identical non-map builds and types from rc.1 to rc.3, so no runtime source changed; the compatibility statement is widened and development dependencies move to rc.3. |
0.7.10 (published) | 0.2.2-rc.1; earlier verified releases listed below | Compatibility release for rc.1 with Cordis 4.1.0 / Schemastery 3.19.0 development dependencies; no runtime source changes. |
0.7.9 (published) | 0.2.2-alpha.3; earlier verified releases listed below | Fixes the remote directory picker being clipped by alpha.3's mobile sidebar drawer; updates compatibility metadata and development dependencies. Corrects stale security a |