dsh-sev README

The project's README from github.com/Buzzso/dsh-sev. As one markdown file: README.md.

dsh-sev

Remote DSH host management for DeepSeek Harness — run a headless dsh instance on your own server and operate it from your local GUI, as if it were a local workspace. Long-running tasks survive your laptop being off.

中文简介：把一台服务器变成你的 DSH「分身」——本地 GUI 左侧边栏混排远程会话、一键打开远程 GUI、SSH 隧道掉线自动重连。长任务甩给服务器，关掉 Mac 也不中断。

✨ Features

🏗 Architecture

┌─ your machine (local dsh) ────────────────────────────┐
│  web GUI  ⇄  /api/dsh-sev/*  ⇄  Node half             │
│   · browser half: sidebar entry, mixed session list   │
│   · node half: registry, tunnel lifecycle, watchdog    │
└──────────────┬────────────────────────────────────────┘
               │ ssh -L <local>:127.0.0.1:<remote dsh port> <alias>
               ▼
┌─ your server (headless dsh, systemd) ─────────────────┐
│  dsh --profile web --host 127.0.0.1 --port 3080        │
│  sessions persist here; long tasks survive laptop off  │
└────────────────────────────────────────────────────────┘

📦 Install

# on the machine running the local DSH GUI
npm i -g pnpm                                   # dsh plugin CLI needs pnpm
dsh plugin --profile web add dsh-sev
# restart the DSH host / web GUI to load the plugin

From source

git clone <this-repo> && cd dsh-sev
npm install && npm run build
dsh plugin --profile web add link:$(pwd)

🖥 Server setup (the "remote host")

Install a headless DSH on the server (Ubuntu 22.04+ example):

# 1. Node + dsh (use a mirror if you are in CN)
npm i -g pnpm
npm i -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com

# 2. Model credentials — the remote instance needs its own API keys:
#    ~/.dsh/settings.yaml          (default model / provider)
#    ~/.dsh/.credentials.yaml      (DeepSeek / provider keys)
#    ~/.modlens/config.json        (vision bridge, if used)
#    export ARK_PLAN_API_KEY=...   (env-based providers, if used)

# 3. systemd unit so it survives reboots (adjust paths)
sudo tee /etc/systemd/system/dsh-web.service >/dev/null <<'EOF'
[Unit]
Description=DSH web (remote host)
After=network-online.target

[Service]
Type=simple
User=<your-user>
Environment=DSH_HOME=/home/<your-user>/.dsh
WorkingDirectory=<dsh-install-dir>
ExecStart=/usr/bin/node <dsh-install-dir>/node_modules/@deepseek-ai/dsh/lib/bin.js --profile web --host 127.0.0.1 --port 3080
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload && sudo systemctl enable --now dsh-web

Tip: replicate your local ~/.dsh (settings, credentials, memories, plugin profile) to the server once — the linked plugin sources resolve by relative symlink when kept at the same path. See docs/server-migration.md.

🌐 Networking

The tunnel uses your normal ssh — any reachable address works:

Example ~/.ssh/config:

Host my-server
    HostName 203.0.113.1          # your server's ZeroTier / LAN IP
    User your-user
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

🚀 Usage

  1. After installing, refresh the GUI. You'll see:
    • a 远程 entry in the left sidebar nav,
    • a 远程会话 group above the workspace list (once a host is online).
  2. Open the 远程 panel, type the SSH alias (e.g. my-server), click 添加.
  3. The plugin auto-starts the tunnel (ssh -L) and shows the host 在线 with its session list.
  4. Click any remote session (or 打开) to operate the remote GUI inside the panel.

Hosts persist in ~/.dsh/remote-hosts.json (with a rolling remote-hosts.json.bak backup).

🔒 Security

🤖 Agent control (one-shot remote tasks)

After install, the local agent gains a sev_run_task(host, task) tool that runs a task on the remote host through its own headless dsh CLI (ssh + dsh --profile headless). Just ask: "run this on the server: …".

Server-side headless setup (once):

# 1. a dedicated DSH_HOME with the plain DeepSeek provider
mkdir -p ~/.dsh-headless
cat > ~/.dsh-headless/settings.yaml <<'CFG'
llm-deepseek:
  baseURL: https://api.deepseek.com
agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash
  reasoningEffort: high
CFG
ln -s ~/.dsh/.credentials.yaml ~/.dsh-headless/.credentials.yaml

# 2. enable the built-in (but disabled) DeepSeek provider for the headless profile
dsh plugin --profile headless add @deepseek-ai/dsh-llm-deepseek
mkdir -p ~/.dsh-headless/profiles/headless
cat > ~/.dsh-headless/profiles/headless/cordis.patch.yml <<'CFG'
- enable:
    - id: llm-deepseek
CFG

Notes: the provider id is deepseek-official; the headless profile ships llm-deepseek disabled by default — the patch above enables it. The tool pipes the task via stdin to a temp file (safe for arbitrary quoting) and times out after 5 minutes.

🛠 Development

npm install        # dev deps: esbuild / typescript / @types/react
npm run build      # bundles lib/client.js (browser half)
npm test           # node --test (11 cases: routes, fence, watchdog, sessions proxy, .bak)
npm run typecheck  # optional tsc --noEmit

Plugin layout:

lib/index.js          # Node half: registry, tunnels, watchdog, /api/dsh-sev routes
src/client/index.tsx  # Browser half: sidebar entry, mixed list, panel, iframe
scripts/build.mjs     # esbuild → lib/client.js (window.__ModuleLoader__.load format)
cordis.patch.yml      # bundle layer manifest (id: sev / name: dsh-sev)

📦 Publishing

npm run build && npm test   # prepublishOnly runs this automatically
npm publish                 # requires an npm account; the package is the "installer"

For the DSH plugin marketplace: install the published package via dsh plugin add dsh-sev; marketplace inclusion follows the DSH plugin registry process.

📄 License

MIT

中文文档

✨ 功能特性

🏗 架构

┌─ 本机（本地 dsh）──────────────────────────────┐
│  web GUI  ⇄  /api/dsh-sev/*  ⇄  Node 半         │
│   · 浏览器半：侧边栏入口、混排会话列表            │
│   · Node 半：注册表、隧道生命周期、看门狗         │
└──────────────┬──────────────────────────────────┘
               │ ssh -L <本地端口>:127.0.0.1:<远程 dsh 端口> <别名>
               ▼
┌─ 服务器（headless dsh，systemd）─────────────────┐
│  dsh --profile web --host 127.0.0.1 --port 3080   │
│  会话持久在服务器；长任务不因本机关机而中断        │
└──────────────────────────────────────────────────┘

📦 安装

从 npm 安装（推荐）

# 在本机（运行 DSH GUI 的机器）
npm i -g pnpm                                   # dsh 插件 CLI 需要 pnpm
dsh plugin --profile web add dsh-sev
# 重启 DSH host / web GUI 使插件生效

从源码安装

git clone <本仓库> && cd dsh-sev
npm install && npm run build
dsh plugin --profile web add link:$(pwd)

🖥 服务器部署（「远程分身」）

在服务器上装 headless DSH（Ubuntu 22.04+ 示例）：

# 1. Node + dsh（国内可用镜像加速）
npm i -g pnpm
npm i -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com

# 2. 模型凭据——远程实例需要自己的 API key：
#    ~/.dsh/settings.yaml          （默认模型 / 提供商）
#    ~/.dsh/.credentials.yaml      （DeepSeek / 各厂商 key）
#    ~/.modlens/config.json        （视觉桥，如使用）
#    export ARK_PLAN_API_KEY=...   （基于环境变量的提供商，如使用）

# 3. systemd 守护，重启不丢（按需改路径）
sudo tee /etc/systemd/system/dsh-web.service >/dev/null <<'EOF'
[Unit]
Description=DSH web (remote host)
After=network-online.target

[Service]
Type=simple
User=<你的用户名>
Environment=DSH_HOME=/home/<你的用户名>/.dsh
WorkingDirectory=<dsh 安装目录>
ExecStart=/usr/bin/node <dsh 安装目录>/node_modules/@deepseek-ai/dsh/lib/bin.js --profile web --host 127.0.0.1 --port 3080
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload && sudo systemctl enable --now dsh-web

提示：可以把本机 ~/.dsh（settings、credentials、memories、插件 profile）一次性复制到服务器——link 插件按相对路径解析，保持同路径即可。详见 docs/server-migration.md。

🌐 组网

隧道用你现有的 ssh，任何可达地址都行：

~/.ssh/config 示例：

Host my-server
    HostName 203.0.113.1          # 你的服务器 ZeroTier / 局域网 IP
    User your-user
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

🚀 使用

  1. 安装后刷新 GUI，你会看到：
    • 左侧导航栏的 远程 入口，
    • 工作区列表上方的 远程会话 分组（主机在线后出现）。
  2. 打开 远程 面板，输入 SSH 别名（如 my-server），点 添加。
  3. 插件自动建立隧道（ssh -L）并显示主机 在线 与会话列表。
  4. 点任意远程会话（或 打开）即可在面板内操作远程 GUI。

主机配置持久化在 ~/.dsh/remote-hosts.json（每次保存自动留 remote-hosts.json.bak 备份）。

🔒 安全

🤖 Agent 控制（一次性远程任务）

安装后，本地 agent 会获得 sev_run_task(host, task) 工具——通过远程主机自己的 headless dsh CLI（ssh + dsh --profile headless）跑任务。直接说「帮我在服务器上跑：…」即可。

服务器端 headless 一次性配置：

# 1. 独立 DSH_HOME + 原生 DeepSeek 提供商
mkdir -p ~/.dsh-headless
cat > ~/.dsh-headless/settings.yaml <<'CFG'
llm-deepseek:
  baseURL: https://api.deepseek.com
agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash
  reasoningEffort: high
CFG
ln -s ~/.dsh/.credentials.yaml ~/.dsh-headless/.credentials.yaml

# 2. 启用 headless 内置（默认禁用）的 DeepSeek 提供商
dsh plugin --profile headless add @deepseek-ai/dsh-llm-deepseek
mkdir -p ~/.dsh-headless/profiles/headless
cat > ~/.dsh-headless/profiles/headless/cordis.patch.yml <<'CFG'
- enable:
    - id: llm-deepseek
CFG

注意：provider id 是 deepseek-official；headless profile 默认禁用了 llm-deepseek，上面的 patch 即启用它。任务文本经 stdin 写入临时文件（任意引号都安全），5 分钟超时。

🛠 开发

npm install        # devDeps: esbuild / typescript / @types/react
npm run build      # 打包 lib/client.js（浏览器半）
npm test           # node --test（11 用例：路由/围栏/看门狗/会话代理/.bak）
npm run typecheck  # 可选 tsc --noEmit

插件结构：

lib/index.js          # Node 半：注册表、隧道、看门狗、/api/dsh-sev 路由
src/client/index.tsx  # 浏览器半：侧边栏入口、混排列表、面板、iframe
scripts/build.mjs     # esbuild → lib/client.js（window.__ModuleLoader__.load 格式）
cordis.patch.yml      # bundle 层清单（id: sev / name: dsh-sev）

📦 发布

npm run build && npm test   # prepublishOnly 会自动执行
npm publish                 # 需要 npm 账号；发布的包就是「安装包」

接入 DSH 插件市场：用 dsh plugin add dsh-sev 安装已发布包；市场收录按 DSH 插件注册流程。

📄 License / 许可证

MIT

dsh-sev (Buzzso/dsh-sev)

Searching Database…

136 ·GitHub
Dsh-sev
这是什么?dsh-sev 是 DeepSeek Harness(DSH)的一个插件,让你在远程服务器上运行无头 dsh 实例,并通过 SSH 隧道从本地 DSH 图形界面控制它,这样即使笔记本关机,长时间运行的任务也能继续。
这是独立应用,还是对已有东西的扩展?它是一个扩展现有 DSH 桌面图形界面的插件,增加了远程面板和混合会话列表,而不是作为单独的应用运行。
这个要怎么设置?通过 npm(或从源码)把插件装进本地 DSH,在服务器上装一个无头 DSH(附有 Ubuntu 22.04+ 示例),然后在 Remote 面板里添加服务器的 SSH 别名——插件会自动启动 SSH 隧道。
需要先有自己的 SSH 可达服务器吗?需要——你得有一台可通过 SSH 访问的服务器(通过 ZeroTier、VPN、局域网或带密钥的公网 IP),上面装好无头 DSH;本地还需要 Node.js 18+ 来运行插件本身。
这会把我的服务器暴露到互联网上吗?不会——远程 dsh 只绑定 127.0.0.1,而且每个插件 API 路由都强制仅限环回访问,唯一的入口就是你的 SSH 隧道。
我的模型 API 密钥最终会在哪里?API 密钥只会存在于你控制的机器上——你的本地机器和你自己的服务器——因为连接只是通过隧道使用你已有的 SSH 密钥。
自动修复(auto-heal)功能是怎么工作的?一个看门狗会监控 SSH 隧道,掉线时自动重连;应用重启时,隧道也会自动恢复。
能在本地应用里看到远程图形界面吗?可以——点一下就能在面板内以 iframe 形式打开远程实例的完整网页界面,或在单独的标签页里打开。
远程主机配置是怎么存储的?主机信息保存在 ~/.dsh/remote-hosts.json 的纯 JSON 文件里,自动做滚动 .bak 备份,删除主机需要确认。
怎么从 DSH 市场安装已发布的插件?运行 `dsh plugin add dsh-sev` 安装已发布的包;进入市场遵循标准的 DSH 插件注册流程。
What are similar projects?dsh-pocket, omnyssh, dsh-web, dsh-bridge, dsh-remote-web-gateway, dsh-mobile, cocode, dsh-dafeiyu
Which topics is it in?ssh-tunnel, remote-access, ssh, dsh, dsh-plugin, deepseek-harness, networking, gui, security, npm, tool, server
Creator
Buzzso
Size
0.1 MB
Stars
136
Updated
CommitAug 27Releasev0.3.4Aug 27
Age
1mo
Commits · 90 Days