dsh-remote-access-qr

dsh-remote-access-qr

Remote access for DeepSeek Harness — scan a QR code and open this machine's DSH Web GUI from a phone. No token to copy, no password prompt.

远程接入（扫码直进）：在 DSH 设置里加一张「远程接入」卡片，点一下按钮，就把本机 DSH 经服务器反向隧道暴露出去，并生成一张二维码；手机扫码直接进入本机 dsh，不需要拼 token、不需要输账号密码。

Status: 0.1.0 — first version, validated end-to-end against DSH Desktop 0.2.1-rc.5 on Windows 11 (client) + Ubuntu 22.04 (server).
版本 0.1.0，在 Windows 11（客户端）+ Ubuntu 22.04（服务器）上端到端验证通过。

---

What it does / 它做什么

Adds a Settings → 远程接入 card with:

• 开启 / 断开远程接入 button
• live status: 已连接 / 连接中 / 异常 / 未开启
• the public 入口地址 and a 直达链接
• a QR code — scanning it opens the public URL, sets a gate cookie, and lands directly in this machine's DSH
• a collapsible run log

Under the hood, one click:

1. reads the local DSH Web listening address from DSH's webServer service;
2. starts an SSH reverse tunnel -R 127.0.0.1:16080:127.0.0.1:<local DSH port> to your server;
3. mints a long-lived signed DSH session cookie locally (from ~/.dsh/.credentials.yaml) and asks nginx on the server to inject it while rewriting Host/Origin to the loopback authority — so DSH's /api trust fence accepts the requests;
4. adds a dshgate cookie gate (/remote-access-enter?k=…) so the QR is the key;
5. runs qrencode on the server and returns the PNG to the card.

---

Requirements / 前置条件

Client (this machine) / 客户端

• DeepSeek Harness Desktop or dsh web (Web GUI), >= 0.2.0-rc.1 < 0.3.0-0
• An SSH key already authorized for the server (auto-detects ~/.ssh/dsh_tunnel_ed25519, ~/.ssh/id_ed25519, ~/.ssh/id_rsa; configurable in the card)
• Windows 10/11 with the built-in OpenSSH client, or another ssh on PATH

Server / 服务器

• Ubuntu/Debian-like Linux with systemd, reachable over SSH as a user that can ssh to the server's root (root@server, configurable user)
• nginx, openssl, qrencode installed (sudo apt install nginx openssl qrencode)
• Port 6080 reachable from the phone (change the listen port in index.js if needed)
• The plugin manages /etc/nginx/sites-available/dsh and /etc/nginx/conf.d/dsh-remote-active.inc; existing content there is overwritten, so use a dedicated server for this

⚠️ The plugin will need root on the server (via your SSH key) to write nginx config, reload nginx and run qrencode.

---

Install / 安装

From the DSH Web UI: Plugins → 添加插件, or from a terminal:

# npm
dsh plugin --profile desktop add dsh-remote-access-qr

# or straight from GitHub
dsh plugin --profile desktop add "git+https://github.com/A754-01/dsh-remote-access-qr.git"

After the first start the card appears under Settings → 远程接入. If you installed from a local checkout, DSH's HMR picks it up without restarting.

---

Configure / 配置

Open Settings → 远程接入 → 设置:

Field	Meaning	Default
服务器	server hostname/IP	(empty — required)
隧道端口	remote loopback port for the reverse tunnel	16080
SSH 用户	SSH user on the server	root
SSH 密钥	private key path	auto-detected
SSH 程序	ssh executable	built-in OpenSSH on Windows

Then press 开启远程接入 and scan the QR code with the phone's camera.

---

Security / 安全说明

• The QR code / 直达链接 contains a random 24-character k; anyone who gets it gets into this machine's DSH — treat it like a password.
• The gate cookie is HttpOnly and valid for one year; it is set once when the QR link is opened.
• Access is plain HTTP unless you put TLS in front of nginx. If the server is on the public internet, consider restricting port 6080 by source IP or adding a certificate.
• The server-side nginx config is generated by the plugin and contains a signed DSH session cookie for the local loopback authority; keep it readable only by the server admin.
• Only one machine can use the configured tunnel port at a time.

---

How it works / 实现

• index.js — Host half: /api/remote-access.{state,start,stop,config} routes; SSH tunnel supervision; cookie minting; nginx registration; QR fetch.
• client.js — Client half: a settings.section card (React from the DSH module table, no bundled React).
• The local DSH port is read from ctx.webServer.getOrigin(); the browser session cookie is minted from $DSH_HOME/.credentials.yaml (client-connection/browser-session), so it survives DSH restarts.

Server files touched while connected:

• /etc/nginx/sites-available/dsh (managed server block, listen 6080 default_server)
• /etc/nginx/conf.d/dsh-remote-active.inc (gate + proxy + injected cookie)
• /tmp/ra-gate-cookies.txt (self-check only)

Pressing 断开远程接入 kills the tunnel and swaps the include file to return 503.

---

Known limitations / 已知限制

• v1 starts/stops manually; it does not auto-connect after a DSH restart.
• Fixed public port 6080; one server serves one active machine at a time on a given tunnel port.
• Linux server with systemd + nginx assumed (Ubuntu 22.04 tested).
• No TLS, no built-in rate limiting.

---

License

MIT © 2026 A754-01