dsh-plugin-qr-connect

English | 中文

A DeepSeek Harness (DSH) Web plugin that adds a QR-code button above the Settings button in the sidebar footer. It runs a small auth-gated reverse proxy so a phone on the same network (or the internet) can scan a QR code and open the web UI securely. It is a persistent bundle plugin (a host half plus a browser half) that loads on every boot.

Demo

What it does

• Adds a full-width button (sidebar.footer.action, id qr-connect) stacked above the shipped Plugins button.
• Opens a fading panel with two QR codes:
  • Local network — http://<lan-ip>:<port>/?auth=<secret>.
  • Public internet — http://<public-ip>:<port>/?auth=<secret> (blue).
• The reverse proxy (a child node process on 0.0.0.0:<port>) validates the secret, issues a session cookie (default 30 days), and forwards to the loopback web UI — including WebSocket upgrades so live updates reach the phone.
• The secret rotates every 30s by default and the QR refreshes to match (configurable; 0 disables auto-refresh).
• Click a QR to copy its link; the public QR has an info tooltip.
• A QR connect card under Settings → Plugins configures the proxy port, session length, and refresh interval.
• English and Chinese UI via DSH's locale service.

Files

File	Purpose
lib/index.js	Host half — runs the reverse proxy and the /__qr/* state routes.
lib/client.js	Browser half — the QR button and the settings card.
lib/proxy.cjs	The auth-gated reverse proxy child process (HTTP + WebSocket).
cordis.patch.yml	Composition patch that inserts the plugin row.
package.json	Package metadata (dsh.bundle + dsh.client manifest).

Install

dsh plugin --profile web add github:mervyn-teo/dsh-plugin-qr-connect

Then restart dsh web — host bundles load at boot.

Defaults live in cordis.patch.yml (port, sessionDays, refreshSeconds, publicHost). Change them there (or in the profile's own cordis.patch.yml) and restart, or adjust them from the settings card — edits are written to the qr-connect settings namespace's user layer, so they survive restarts and layer over the composition defaults. publicHost is a custom domain or IP used for the public-internet QR code instead of the auto-detected public IP (accepts host, host:port, or a full https:// origin; empty = auto-detect). The host half serves three same-origin routes the browser half uses: GET /__qr/info, POST /__qr/rotate, and GET|POST /__qr/config.

Requirements

• DSH with the subprocess, fs, and webServer services mounted, plus the settings service for the Settings → Plugins card (without it the card is hidden and edits stay runtime-only).
• Internet access from the DSH host for the public-IP lookup (https://api.ipify.org).
• The scanning device must be able to reach the proxy port (a host firewall may need an allow rule); the public QR also needs internet reachability (port-forwarding).

Local-IP and public-IP detection run in-process (no ip/curl/shell commands), and manual secret rotation signals the proxy child over its stdin, so the host half works on Windows, macOS, and Linux.

Security

The proxy exposes the full agent shell to anyone who can reach the port, gated only by the 30s secret and the session cookie. Use a short session length and treat this as a trusted-network convenience, not a hardened remote-access layer.

License

MIT