Skip to main content

dsh-web-ui/packages/dsh-remote-web-ui

5.1kStars310Forks49Issues5Watchers

Adds QR code pairing, mobile and PC remote access channels, authorized device management, and one-click public network tunnel capability to dsh web GUI, with version auto-update for the dsh-web-ui bundle.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the zhu1090093659/dsh-web-ui monorepo — stars and activity count the whole repository.

Language
TypeScript
License
Apache-2.0
Branch
dev
deepseek-harnessdshdsh-pluginweb-ui

Install

cmdweb profile
$ dsh plugin --profile web add @linxin666/dsh-remote-web-ui

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin zhu1090093659/dsh-web-ui/packages/dsh-remote-web-ui for me: review the repository at https://github.com/zhu1090093659/dsh-web first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

Adds a QR code pairing remote access panel to the dsh web GUI: mobile phones operate the workspace through the self-implemented /m/ small-screen client, computers run the full Web GUI through the gated /remote/api channel; also includes a one-click update button for the dsh-web-ui family in the sidebar.

Core Capabilities

  • New mobile phone icon entry at the bottom of the sidebar (next to settings button), hover shows "Remote Access" tooltip; panel displays a QR code and generates two one-time pairing links (mobile uses /m/, computer uses /) plus stop/refresh/copy operations
  • Pairing mechanism uses one-time token + device session: once accepted, the other link immediately becomes invalid, token cannot be reused, auto-expires; clicking "Stop" immediately revokes all paired devices' next request permissions
  • Authorized device panel infers device name from User-Agent, shows online/offline status and last activity time, can unpair individual devices; interface does not display device IDs or raw UA as credentials
  • requirePairingForLan enabled by default: when opening desktop Web GUI via LAN or public tunnel, it automatically switches to the gated /remote/api; unpaired devices see a full-screen blocking page (only 127.0.0.1 continues using /api)
  • Independent /m/ interface for mobile: paginated list loading, on-demand message fetching, real-time streaming via SSE, Markdown rendering, model and permission selectors, display toggles and context usage chips, can be installed as PWA (only caches static shell and offline pages)
  • Public tunnel supports two paths: manually fill publicBaseUrl (like Cloudflare named tunnel / Tailscale virtual interface), or enable autoTunnel to let the plugin's built-in cloudflared quick tunnel auto-generate https://*.trycloudflare.com URL
  • Sidebar provides one-click self-update for dsh-web-ui family: checks npm registry for new versions of @linxin666/dsh-* packages, confirms and executes pnpm update --latest within the dsh profile, then verifies version actually changed

Technical Implementation

  • Language: TypeScript (with JSX) + Node.js + React 18 dual half-package
  • Key Dependencies: cloudflared (auto public tunnel binary), qrcode.react (SVG QR code without canvas), schemastery (DSH config schema validation), zod; runtime injects React 18 as peer
  • Architecture Pattern: Dual half-package cordis bundle: src/index.ts is the host half (pairing service + /api/pair + /m/api + /remote + /api/update routes + gate listener + posture detection), src/client/index.ts is the browser half (sidebar entry, pairing panel, pairing failure notification, settings card, mobile deep-link + heartbeat + remote desktop channel); cordis inject=['webServer','apiProxy'], dsh.client.platform='web'
  • Entry Files: src/index.ts (host entry, export const name='remote-web-ui' + apply mounts all routes and gates), src/client/index.ts (browser entry, registers sidebar.remote/sidebar.footer.action/webServer.plugin.item three slots)

Use Cases

  • While commuting, at home, or in meetings, want to continue processing workspace, sessions, and chat history from the computer on the phone, without leaving the computer on a public network
  • On business trips or temporarily at home, want to access the dsh web running in the studio from anywhere via public tunnel, while keeping the workspace and sessions completely local without going out to the network
  • Team maintaining dsh-web-ui family, wants admins and end users to one-click update plugins and skin families to latest in the sidebar, no longer manually running pnpm update

Prerequisites & Compatibility

DependencyMinimum VersionDescription
DSHLocked via devDependencies to @deepseek-ai/dsh-client-* ^0.1.0-rc.8Requires SDK to expose webServer, apiProxy, settings.section, sidebar.remote/sidebar.footer.action, api/gate and other seams; api/gate listener doesn't emit in released SDK (src/index.ts:41-56)
Node^22.19.0 or >=24.0.0From package.json:7-9
PlatformCross-platformBrowser side platform: 'web'; auto public tunnel available on macOS / Linux / Windows (Windows uses cmd.exe to parse npm-installed .cmd shim)
Native Modulecloudflared ^0.7.3 binary (auto-downloaded in postinstall)Can also be overwritten at runtime to skip postinstall (README.zh.md:34)
Startup Parameter--host 0.0.0.0Required in LAN scenarios; 127.0.0.1 single binding shows clear unusable prompt in panel (unless publicBaseUrl is configured)

Installation

dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-remote-web-ui

Configuration Options

ConfigTypeDescriptionDefault
enabledbooleanMaster switch: disables sidebar entry and deactivates pairing routes and LAN fence when closedtrue
tokenTtlMsnumberOne-time pairing token validity period; QR code expires after this600000 (10 minutes)
offlineAfterMsnumberHow long without heartbeat before paired device is considered offline25000
maxDevicesnumberMaximum paired devices to keep simultaneously; exceeds this淘汰最旧4 (range 1–64)
idleExpireMsnumberMilliseconds of inactivity before considered idle expired (gets deleted, must re-scan QR)604800000 (7 days)
cookieNamestringCookie name carrying paired device ID; changing it invalidates old devicesdsh_pair
requirePairingForLanbooleanWhether LAN / tunnel access to desktop Web GUI requires pairing; when off, desktop continues using normal /apitrue
publicBaseUrlstringPublic tunnel address (e.g., https://xxx.trycloudflare.com); non-http(s) URLs are ignored and warned; this field is ignored when autoTunnel is enabledempty
autoTunnelbooleanStarts plugin's built-in Cloudflare quick tunnel, dynamically generates public address and writes to QR base and mobile's trust listfalse
mobileEnterToSendbooleanSend semantics for mobile chat input: true = Enter sends, Shift+Enter newline; false = Enter newline, can only click send buttontrue

FAQ

Q: What does this plugin do?

A: Adds QR code pairing remote access to dsh web GUI — phones open independent /m/ mobile interface, computers use full Web GUI through the gated /remote/api channel; also adds a "Check Updates" button in sidebar bottom-right to one-click update dsh-web-ui family.

Q: Can I use it at home? What are the prerequisites?

A: Only localhost loopback (127.0.0.1) works immediately; for phone to access computer, dsh web must be started bound to all interfaces (dsh web --host 0.0.0.0), otherwise panel shows clear prompt and refuses to generate scannable QR code (unless you've filled in public address in settings or enabled autoTunnel).

Q: What's the security model? Can pairing tokens be reused?

A: Only one valid one-time token exists at any moment; once any device accepts, the other link immediately becomes invalid, reusing an already-accepted token is rejected; it also auto-expires after tokenTtlMs (default 10 minutes). Clicking "Stop" revokes all paired devices' sessions, next request gets 403. After dsh web restarts, device cookies remain valid but current QR code is invalidated, must refresh.

Q: What's the difference between mobile interface and small-screen desktop browser?

A: Uses the plugin's own /m/ mobile client, not desktop Web GUI crammed into phone — paginated lists, on-demand message fetching, conversation folding (deep thinking/tool calls become expandable rows), input has model selection, permission selection, display toggles and context usage chips; can be installed as PWA, but Service Worker only caches static shell and offline pages, runtime still requires DSH online.

Q: Will unpaired computers in LAN be blocked?

A: Yes by default. When requirePairingForLan is on (default), any desktop Web GUI opened from non-loopback address (LAN or public tunnel) switches to gated /remote/api, must carry valid device pairing cookie; unpaired computers see full-screen blocking page, no workspace data. "Stop" button immediately cuts off paired devices.

Q: Does auto public tunnel expose my service? Need an account?

A: Yes, Cloudflare quick tunnel lets anyone with https://*.trycloudflare.com URL load static page, but all data channels (/m/api and /remote/api) use paired device cookie + method whitelist as real fence — unpaired calls get 403. No account or domain needed, cloudflared binary ships with plugin (depends on cloudflared ^0.7.3).

Q: Can one phone connect simultaneously? What's the limit?

A: Yes, but with a limit. maxDevices config (default 4, range 1-64) controls max paired device sessions to keep simultaneously; when exceeded, oldest gets淘汰; devices without heartbeat or gated requests for 7 days auto-expire.

Q: What to watch out for when deploying dsh web on public network?

A: Plugin actively probes SDK's /api trust fence — once it finds --trusted-host lets some host bypass fence, sources other than pairing can also read /api, it shows red banner in panel with CRITICAL log warning; recommend removing --trusted-host for that source and using this plugin's pairing channel instead. Cloudflare quick tunnel / Tailscale Serve etc. that don't forward SSE will cause mobile chat real-time messages to degrade to short-interval polling; only cloudflared named tunnel or ssh -L port forwarding preserve SSE.

Difficulty Level

Beginner — After installation, mobile phone icon appears at sidebar bottom, clicking gives QR code; every step from localhost to LAN to public network has panel prompts and one-click switches, ordinary users can complete first pairing by following prompts; if need to configure autoTunnel, publicBaseUrl, or custom device limit, need to go to settings page "Remote Access Settings" card to edit.

Known Issues & Limitations

  • Revocation takes effect per-request: When stopped, in-flight device requests complete normally, next request gets 403 (README.zh.md:173)
  • Paired device sessions persist to disk by default: Device sessions (excluding one-time QR token) written to $DSH_HOME/remote-web-ui-devices.json (0600, temp file + atomic rename); after dsh web restart, cookies remain valid but current QR code needs refresh. idleExpireMs defaults to 7 days (README.zh.md:174)
  • Quick tunnel hostname changes each run: Cloudflare quick tunnel URL differs each time cloudflared starts, publicBaseUrl must be updated with tunnel restart; using cloudflared named tunnel (domain hosted on Cloudflare) gives stable hostname, also required for persistent PWA installation (README.zh.md:120-122)
  • Tunnels not forwarding SSE degrade real-time messages to polling: Cloudflare quick tunnel / Tailscale Serve / single-port tailscale serve don't forward Server-Sent Events, mobile chat on public path briefly polls; other mobile features unaffected (README.zh.md:121-122, src/mobile/mux.ts:277)
  • LAN HTTP cannot install /m/ PWA: To install /m/ as PWA on mobile needs secure context; localhost / 127.0.0.1 work for localhost but phone installation needs HTTPS; regular LAN HTTP still works for mobile remote control, just can't register Service Worker (README.zh.md:35)
  • pnpm 11 minimumReleaseAge gate makes one-click update silently skip same-day release: Update command exits green but version unchanged reports "Update failed" and gives minimumReleaseAgeExclude config guide, rather than false success (src/client/locales.ts:155-158, src/index.ts:336-353)
  • Mobile Markdown doesn't support KaTeX formulas: Mobile bundle uses zero-dependency GFM Markdown renderer (headings/bold/italic/inline code/code blocks/lists/tables/quotes/links/images, escape then whitelist protocols), KaTeX formulas not supported (README.zh.md:67, README.md:193)
  • Posture detection finding /api fence open emits CRITICAL log: Any non-403 probe result logs CRITICAL in plugin and shows red banner in panel (src/index.ts:394-398)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/zhu1090093659/dsh-web-ui/packages/dsh-remote-web-ui)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory