dsh-tunnelmux-remote

dsh-tunnelmux-remote

Mobile remote control for the DeepSeek Harness web GUI, with TunnelMux as the
tunnel backend. Scan a QR code beside the sidebar to pair your phone, chat
with your sessions from /m, and revoke any device at any time. The public URL
comes from the local TunnelMux control API (cloudflared/ngrok) — no embedded
tunnel binary in the plugin.

Built from scratch (2026-08-16) following the design in
TunnelMux docs/plans/2026-08-16-dsh-tunnelmux-remote-design.md
and referencing @linxin666/dsh-remote-web-ui (Apache-2.0) for the pairing model.

Features

• Scan-to-pair QR beside the official sidebar footer: one-time token, first
  accept consumes it, refresh invalidates the old QR immediately.
• Device sessions: HttpOnly cookie gate, presence tracking with offline
  detection, max 4 devices (oldest evicted), revoke all with one click.
• Mobile surface at /m: session list (cursor pagination), create /
  rename / history / prompt / models — bridged through the host apiProxy with a
  strict method allowlist.
• TunnelMux backend: POST /v1/tunnel/start returns the public URL
  synchronously (daemon waits for provider startup); the plugin observes
  status for the panel and never restarts the tunnel itself — the daemon owns
  auto_restart.
• Live updates: SSE /api/pair/events for the desktop panel and
  /m/api/events.mux for the phone.

Install

Requires a running TunnelMux daemon (control API on 127.0.0.1:4765) and the DSH
web profile:

cd ~/.dsh/profiles/web
dsh plugin add github:kexuejin/dsh-tunnelmux-remote   # or link:/path/to/this/repo

Or add to cordis.patch.yml manually:

- insert:
    - id: tunnelmux-remote
      name: dsh-tunnelmux-remote

Configuration (settings namespace tunnelmux-remote)

key	default	meaning
enabled	true	master switch
tunnelmuxBaseUrl	http://127.0.0.1:4765	TunnelMux control API
tunnelmuxApiToken	'' (secret)	optional Bearer token
targetUrl	http://127.0.0.1:3080	local GUI the tunnel exposes
tunnelProvider	cloudflared	cloudflared or ngrok
autoTunnel	false	start the tunnel on plugin load
publicBaseUrl	''	existing public entry (skips auto-tunnel)
tokenTtlMs / offlineAfterMs / maxDevices	10min / 25s / 4	pairing tuning
cookieName	dsh_pair	device cookie
mobileEnterToSend	true	Enter sends in the phone chat box

Security model

• One active token; issue() replaces it, so a fresh QR invalidates the
  previous link immediately.
• One-time accept; reuse returns used (409). Tokens expire (default
  10 min). stop() revokes every session and clears the token — the phone's
  next gated request gets 403.
• Fences: control endpoints (issue/stop/events) are loopback-only;
  phone endpoints (accept/heartbeat/status) allow loopback, LAN
  literals, or the public tunnel Host. Accept is rate-limited per IP
  (10 attempts / 30 s).
• Mobile allowlist: only workspace.list, session.* and
  mobile.preferences are exposed over /m/api; everything else 403s.
  settings.* / credentials.* remain loopback-only host methods and are
  never reachable from a phone.

Development

npm install
npm run typecheck   # tsc client + host
npm test            # vitest (48 tests)
npm run build       # tsdown: lib/index.js (host) + lib/mobile.js + client/client.js
node test/smoke-live.mjs   # read-only probe of a live daemon at 127.0.0.1:4765

License

Apache-2.0.