@dshfly/remote-connector

English · 简体中文

Overview

A cordis plugin for DeepSeek Harness (DSH): it turns your phone into a remote control and inbox for DSH running on your PC. Watch and manage DSH sessions from your phone, follow progress, and approve requests right on the phone. Pairing is a QR scan (both sides compare a short code), and you can pair several phones with several PCs — or share one workspace or session with a colleague's phone for collaboration. Native push notifications keep you posted when tasks move.

Traffic goes through a cloud relay with the PC dialing out — no public IP or port forwarding needed. Session content is end-to-end encrypted (E2EE): the relay only forwards ciphertext, cannot decrypt it, and does not store it. The one exception is the session title and sessionId required for push notifications (plaintext metadata — see Security below).

The phone side uses the DSH Fly app to scan and pair; iOS / Android / Harmony versions are rolling out.

Implementation notes

• Outbound reverse connection: the PC dials out to the cloud relay (works behind home NAT/CGNAT).
• E2EE endpoint: decrypts phone ciphertext → plaintext over loopback to dsh web; encrypts downstream events back to the phone.
• /dshfly control route (loopback-only): pairing QR, device management, second confirmation.
• Mobile plugin host: ships an in-package ctx.mobileBridge service (mobile plugin spec implementation).

Data path: phone app ──E2EE──▶ cloud relay (ciphertext only; push metadata excepted) ──E2EE──▶ this plugin ──loopback──▶ dsh web (127.0.0.1:3080).

Install

# Zero config: built-in relayUrl https://relay.dshfly.com, device identity auto-generated (no account, no login)
dsh plugin --profile web add @dshfly/remote-connector
dsh web   # restart to apply

Pairing: open the dsh web settings page → DSH Fly → "New pairing" → scan the QR from the phone → both sides show an 8-character short code; confirm on the PC only after they match → done. The phone is ready immediately (workspaces / sessions / approvals / file browsing …).

The short code is the pairing anchor: both sides show the same code, and a mismatch means the relay may be tampered with — tap "Reject". The server verifies this code too (missing or mismatched codes are always rejected), so don't use third-party clients that skip the comparison.

Requirements

• DSH: verified against 0.1.5-rc.1; 0.1.2+ is expected to work, older versions are unverified (the plugin has no runtime DSH version gate yet — see docs/compatibility.md P0-6). dsh web must bind loopback (127.0.0.1) — the pairing control route carries one-time secrets and the plugin enforces loopback-only.
• Node >= 22.

Security

• E2EE: session content and code diffs are end-to-end encrypted; the cloud relay only routes ciphertext and cannot read them; the encryption endpoints are your phone and this plugin. dsh web always binds loopback and is not exposed publicly. ⚠️ Exception (plaintext metadata): the session title and sessionId needed for push notifications must be handed to the relay in plaintext (it forwards them through an aggregation channel to APNs/FCM and similar vendors). This part is not covered by E2EE.
• Pairing anchor: one-time pairing code + local public-key fingerprint + short-code comparison on both sides (enforced server-side) + device identity pinned on confirm; keys live in <dshHome>/dshfly/keys.json (mode 0600, directory 0700).
• File access is scope-bound: by default ("full disk" off) only registered workspaces are reachable, and secrets/credentials (.env, .ssh, .git, .aws, DSH's own keys.json / .credentials.yaml, …) are never readable; enabling "full disk" runs that device with full-disk permissions (no longer subject to that list) — enable it only for devices you fully trust.
• Collaboration guests (if enabled): they can only reach the sessions/workspaces granted to them — read and chat, but cannot approve tool calls or change configuration; dot-directories (.git, .github, …) are invisible to guests.
• The plugin is a fail-loud host: recoverable problems (e.g. missing config) log a warning and skip startup instead of taking dsh web down.

Configuration (optional)

Zero config works out of the box. To override, target the plugin by id in the profile's user patch layer (~/.dsh/profiles/web/cordis.patch.yml), then restart dsh web (dsh web --dump-config prints the composed tree to verify):

- id: dshfly-remote-connector
  config:
    relayUrl: https://relay.example.com   # for a self-hosted relay
    target: http://127.0.0.1:3080         # when dsh web uses a non-default port

An id-targeted patch replaces the whole config of the matched row (no deep merge); the plugin falls back to built-in defaults for keys you omit, so write only what you change.

| Key | Default | When to change | |---|---|---| | relayUrl | https://relay.dshfly.com | self-hosted relay | | target | http://127.0.0.1:3080 | dsh web on another port |

The remaining keys are for troubleshooting / multi-instance setups (keysPath, deviceName, profileName / profileDir, dshBin, recommendedPlugins); the full list and notes live in the plugin repository's docs/connector-plugin.md §5.4. Pay special attention to keysPath: changing the path = a different device (paired phones must re-scan), and its directory is unreadable to collaboration guests / restricted devices — do not point it into a shared workspace.

English · 简体中文

概述

DeepSeek Harness (DSH) 的 cordis 插件:把手机变成 PC 上 DSH 的遥控器与收件箱。可从手机远程查看和管理 PC 上的 DSH 会话、随时看进度、直接在手机上审批。扫码即可配对(两端核对短码),支持多手机 + 多 PC,也可以把某个工作区或会话共享给同事的手机协作。内置原生消息推送,任务有动静即时通知。

远程链路走云端中继:PC 主动出站,无需公网 IP 或端口映射;会话内容端到端加密(E2EE),中继只转发密文、既解不开也不存储。唯一例外是推送所需的会话标题与 sessionId(明文元数据,见下文「安全」)。

手机端用 DSH Fly App 扫码配对;App 提供 iOS / Android / Harmony 版本,正在陆续上架。

实现要点

• 出站反向连接:PC 主动拨出到云端中继(绕开家庭 NAT/CGNAT)。
• 端到端加密 (E2EE) 终点:解手机密文 → 明文走 loopback 转 dsh web;把下行事件加密回手机。
• /dshfly 控制路由(loopback-only):配对 QR、设备管理、二次确认。
• 移动端插件承载:随包内置 ctx.mobileBridge 服务(移动端插件规范实现)。

数据面:手机 App ──E2EE──▶ 云端中继(只见密文;推送元数据除外)──E2EE──▶ 本插件──loopback──▶ dsh web (127.0.0.1:3080)。

安装

# 零配置:relayUrl 内建默认 https://relay.dshfly.com,设备身份自动生成(无账号、无登录)
dsh plugin --profile web add @dshfly/remote-connector
dsh web   # 重启生效

配对:打开 dsh web 设置页 → DSH Fly → 「新建配对」→ 手机扫码 → 两端都显示 8 位短码,核对一致后在 PC 端点确认 → 完成。手机端随即可用(工作区/会话/审批/文件浏览……)。

短码是配对的安全锚点:两端显示同一个码,不一致说明中继可能被篡改,请点「拒绝」。服务端也会校验该短码 (缺失或不符一律拒绝),所以请勿用会跳过比对的第三方客户端。

要求

• DSH:本版本实测基线 0.1.5-rc.1;0.1.2+ 预期可用,更早版本未验证(插件暂无运行期 DSH 版本门禁, 见 docs/compatibility.md P0-6)。dsh web 必须绑定 loopback(127.0.0.1)——配对控制路由含一次性密钥, 插件会强制校验。
• Node >= 22。

安全

• E2EE:会话内容与代码 diff 走端到端加密,云端中继只路由密文、读不到;加密终点是手机与本插件。dsh web 恒绑 loopback,不暴露公网。 ⚠️ 例外(明文元数据):消息推送所需的会话标题与 sessionId 必须明文交给中继(中继还要经聚合通道转 APNs/FCM 等厂商),这部分不属于 E2EE 保护范围。
• 配对锚定:一次性配对码 + 本机公钥指纹 + 两端短码比对(服务端强制校验)+ 确认后固定设备身份;密钥存 <dshHome>/dshfly/keys.json(0600,目录 0700)。
• 文件访问受作用域约束:默认(未开「完整磁盘」)只允许已登记工作区内,且密钥/凭据类(.env、.ssh、.git、.aws、DSH 自己的 keys.json / .credentials.yaml 等)一律不可读;开启「完整磁盘」= 该设备按完整磁盘权限运行(不再受该名单限制),请只对自己完全信任的设备开启。
• 协作访客(如启用):只能访问被授予的会话/工作区,可看、可对话,但不能批准工具调用、不能改配置;点目录(.git、.github 等)对访客不可见。
• 插件是 fail-loud 宿主:配置缺失等可恢复情况会 warn + 跳过启动,绝不拖垮 dsh web。

配置(可选)

默认零配置即可用。需要覆盖时,在 profile 的用户覆盖层 ~/.dsh/profiles/web/cordis.patch.yml 里按插件 id 覆盖, 改完重启 dsh web(dsh web --dump-config 可核对是否生效):

- id: dshfly-remote-connector
  config:
    relayUrl: https://relay.example.com   # 自建中继时覆盖
    target: http://127.0.0.1:3080         # dsh web 非默认端口时

id-targeted patch 会整体替换匹配行的 config(不做深合并);本插件对未写的键有内置默认值兜底,所以只写要改的键即可。

| 键 | 默认 | 何时需要改 | |---|---|---| | relayUrl | https://relay.dshfly.com | 自建中继 | | target | http://127.0.0.1:3080 | dsh web 换端口 |

其余键属排障/多开场景(keysPath、deviceName、profileName/profileDir、dshBin、recommendedPlugins), 完整清单与说明见插件仓库的 docs/connector-plugin.md §5.4。其中 keysPath 需特别注意:换路径 = 换一台设备 (已配对手机要重新扫码),且它所在目录对协作访客/受限设备是禁读的——不要指向共享工作区。

License

MIT