smanx/deepseek-harness repository overview

⁠deepseek-harness (Docker Image)

Image (default): smanx/deepseek-harness:latest (Docker Hub) Image (backup): ghcr.io/smanx/deepseek-harness:latest (GitHub Container Registry, GHCR; all tags are mirrored there) Docker Hub project page: https://hub.docker.com/r/smanx/deepseek-harness⁠ Github project page：https://github.com/smanx/deepseek-harness-docker⁠

An out-of-the-box DeepSeek Harness (DSH) Docker image with a built-in Node reverse proxy. It solves the issue that DSH officially forbids --host 0.0.0.0 (loopback-only listening) and makes DSH safely accessible over your LAN.

⁠Online Demo

• Demo URL: https://dsh.smanx.xx.kg⁠
• Username / Password: admin / admin

⁠About the Project

• DSH: Installs the official npm package @deepseek-ai/dsh (deepseek-harness⁠) inside the container, listening on 127.0.0.1:3079 (source port) by default;
• Node proxy: 0.0.0.0:3080 (proxy port) → 127.0.0.1:3079, providing HTTP + WebSocket forwarding to the outside;
• Why a proxy is needed:
  • DSH officially forbids --host 0.0.0.0 (security restriction) and can only listen on the loopback address;
  • Pages loaded over a LAN IP are in a browser non-secure context, where the crypto.randomUUID used by the DSH frontend is unavailable. The proxy automatically injects a getRandomValues-based polyfill into served HTML; without it the realtime channel (WS) stays pending forever;
  • The proxy also provides optional HTTP Basic Auth to protect LAN access.

⁠Quick Start (pull & run)

# 1. Pull the image (default: Docker Hub)
docker pull smanx/deepseek-harness:latest

# 2. Run (defaults: proxy port 3080, data persisted to named volume dsh-data)
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

# 3. Access
#    Local machine: http://127.0.0.1:3080/
#    LAN:           http://<server-LAN-IP>:3080/

The WebSocket realtime channels (/api/events.mux, /api/events.host) are forwarded automatically by the proxy — no extra configuration needed.

⁠Differences between the tags

A simple example:

# Scenario 1: just run DSH in the browser with no debugging → use the slim `latest`
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

# Scenario 2: you need to get inside the container to troubleshoot
# (view logs, process JSON with jq, fetch things with wget) → use devtools-min-latest
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:devtools-min-latest

# Scenario 3: develop/compile inside the container or do heavier ops
# (vim, python3, make, etc.) → use devtools-latest
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:devtools-latest

The run command is identical across all three tags — only the image name (tag) changes. The tooled variants are a bit larger than the slim image, so pick what fits.

The tooled variants (devtools / devtools-min / test) ship with pnpm (installed via npm globally). DSH's dsh plugin command relies on pnpm to manage plugins, and the community plugin market dsh-market⁠ (dsh plugin --profile web add dshmarket) needs it too. The slim latest does not bundle it — on first plugin use, dsh-market detects the missing pnpm and offers one-click automatic setup.

They also ship uv (Python package manager, static binary, no system Python required). Many community MCP servers launch via uvx / uv run (commonly seen in DSH MCP client configs as "command": "uvx") — without uv those MCPs cannot run.

⁠Admin variant (latest DSH pre-installed)

The admin variant pre-installs the latest DSH (@next). After the container starts, the manager service detects and starts DSH automatically, so / serves the DSH UI directly; visiting /__admin/ opens the admin page, where you can:

• Browse available versions of @deepseek-ai/dsh (dist-tags like latest/next plus the full list) and install / switch versions, with live install logs;
• Configure the npm registry (NPM_CONFIG_REGISTRY) manually: the input field auto-fills the default (env NPM_CONFIG_REGISTRY or the official registry) and the last-saved value, and shows the effective value; you can restore the default or clear it with one click. Priority: page config > env NPM_CONFIG_REGISTRY > default;
• Restart DSH with one click. After install it starts automatically, and a floating "⚙ Admin" button stays in the corner of the DSH page so you can always get back to the admin page.

# Admin variant: use two named volumes (dsh-data for DSH config/sessions, dsh-install for the
# installed DSH files and config state, so upgrades/registry survive container recreation)
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  -v dsh-install:/opt/dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:admin-latest

⁠Quick Start (pull & run)

⁠Backup Image (GHCR)

If pulling from Docker Hub is restricted (e.g. network issues), you can use the backup image (GitHub Container Registry; tags are identical to Docker Hub):

# Pull the image from GHCR
docker pull ghcr.io/smanx/deepseek-harness:latest

# Same run command as the default image — just swap the image name
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  ghcr.io/smanx/deepseek-harness:latest

⁠Configuration (Environment Variables)

⁠Enabling Basic Auth

docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  -e PROXY_USERNAME=yourname \
  -e PROXY_PASSWORD=yourpass \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

• Auth is enabled only when both username and password are set; if either (or both) is missing, access is completely open;
• Auth applies to both HTTP and WebSocket. Unauthenticated requests get 401 + WWW-Authenticate, and the browser shows a credential prompt.

⁠Changing the proxy port

# e.g. expose the proxy on port 3088
docker run -d \
  --name dsh-harness \
  -p 3088:3088 \
  -v dsh-data:/root/.dsh \
  -e PROXY_PORT=3088 \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

⁠Data Persistence

DSH session/configuration data lives in /root/.dsh inside the container; the commands above persist it via the named volume dsh-data:

• Data survives docker stop/start and container removal;
• To wipe it completely: docker volume rm dsh-data (stop the container first).

⁠Stop / Restart / Remove

docker stop dsh-harness     # stop
docker start dsh-harness    # start again
docker logs -f dsh-harness  # view logs
docker rm -f dsh-harness    # remove the container (volume data is kept)

⁠Contact & Feedback

• Discussion & bug feedback: https://github.com/deepseek-ai/deepseek-harness/discussions/1762⁠

⁠deepseek-harness（Docker 镜像）

镜像地址（默认）：smanx/deepseek-harness:latest（Docker Hub） 镜像地址（备用）：ghcr.io/smanx/deepseek-harness:latest（GitHub Container Registry，GHCR，所有 tag 同步推送） Docker Hub 项目主页：https://hub.docker.com/r/smanx/deepseek-harness⁠ Github 项目主页：https://github.com/smanx/deepseek-harness-docker⁠

一个开箱即用的 DeepSeek Harness（DSH） Docker 镜像，内置了 Node 反向代理，解决 DSH 官方不允许 --host 0.0.0.0、只能监听回环地址的问题，让 DSH 可以安全地通过局域网访问。

⁠在线体验地址（Demo）

• 体验地址：https://dsh.smanx.xx.kg⁠
• 登录账号 / 密码：admin / admin

⁠项目介绍

• DSH：容器内安装官方 npm 包 @deepseek-ai/dsh（deepseek-harness⁠），默认监听容器内 127.0.0.1:3079（源端口）；
• Node 代理：0.0.0.0:3080（代理端口）→ 127.0.0.1:3079，对外提供 HTTP + WebSocket 转发；
• 为什么需要代理：
  • DSH 官方禁止 --host 0.0.0.0（安全限制），只能监听回环地址；
  • 局域网 IP 页面属于浏览器非安全上下文，DSH 前端依赖的 crypto.randomUUID 不可用，代理在转发 HTML 时自动注入基于 getRandomValues 的 polyfill，否则实时通道（WS）会一直 pending；
  • 代理同时提供可选的 HTTP Basic Auth，给局域网访问加认证。

⁠快速开始（拉取运行）

# 1. 拉取镜像（默认从 Docker Hub 拉取）
docker pull smanx/deepseek-harness:latest

# 2. 启动（默认：代理对外端口 3080，数据持久化到命名卷 dsh-data）
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

# 3. 访问
#    本机：  http://127.0.0.1:3080/
#    局域网：http://<服务器局域网IP>:3080/

WebSocket 实时通道（/api/events.mux、/api/events.host）由代理自动转发，无需额外配置。

⁠不同 tag 的区别

简单示例：

# 场景一：只想在浏览器里跑 DSH，不做任何调试 → 用精简的 latest
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

# 场景二：需要进容器排查问题（看日志、jq 处理 JSON、wget 抓包）→ 用 devtools-min-latest
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:devtools-min-latest

# 场景三：要在容器里开发/编译扩展或做较重的运维（vim、python3、make 等）→ 用 devtools-latest
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:devtools-latest

三个 tag 的启动命令完全一样，只是把镜像名替换成对应的 tag 即可；latest 之外的工具版镜像会比精简版略大，按需选择。

⁠admin 变体（管理版，预装最新 DSH）

admin 变体随镜像预装最新 DSH（@next）。容器启动后管理服务自动识别并拉起 DSH，直接访问 / 即可进入 DSH 界面；访问 /__admin/ 进入管理台：

• 查看 @deepseek-ai/dsh 可用版本（latest/next 等 dist-tag + 全部版本），选择并安装 / 切换版本，安装进度实时显示；
• 手动配置 npm 源（NPM_CONFIG_REGISTRY）：输入框自动回显默认值（环境变量 NPM_CONFIG_REGISTRY 或官方源）与上次配置的值，并显示当前生效值，可一键「使用默认值」或清空恢复默认；优先级：页面配置 > 环境变量 NPM_CONFIG_REGISTRY > 默认值；
• 一键重启 DSH；安装完成后自动启动，页面右下角悬浮「⚙ 管理」按钮可随时回到管理台调整版本。

# admin 变体：需要两个命名卷（dsh-data 存 DSH 配置/会话、dsh-install 存 DSH 安装文件与配置状态，
# 这样容器重建后升级/源配置依然有效）
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  -v dsh-install:/opt/dsh \
  --restart unless-stopped \
  smanx/deepseek-harness:admin-latest

⁠备用镜像（GHCR）

如果从 Docker Hub 拉取受限（如网络问题），可以使用备用镜像（GitHub Container Registry，tag 与 Docker Hub 完全一致）：

# 拉取 GHCR 上的镜像
docker pull ghcr.io/smanx/deepseek-harness:latest

# 启动命令与默认镜像完全一样，只需替换镜像名
docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  --restart unless-stopped \
  ghcr.io/smanx/deepseek-harness:latest

⁠配置（环境变量）

⁠启用 Basic Auth

docker run -d \
  --name dsh-harness \
  -p 3080:3080 \
  -v dsh-data:/root/.dsh \
  -e PROXY_USERNAME=yourname \
  -e PROXY_PASSWORD=yourpass \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

• 用户名和密码两个都设置才启用认证；只设置一个（或都不设置）则完全放行；
• 认证对 HTTP 和 WebSocket 都生效，未通过认证返回 401 + WWW-Authenticate，浏览器会弹出认证框；
• 公开静态资源 /manifest.webmanifest、/favicon.svg、/favicon.ico 不参与认证（只含应用名/图标等非敏感数据）。浏览器抓取 <link rel="manifest"> 时不会携带 Basic Auth 凭据，若强制认证，控制台会持续报 /manifest.webmanifest 401。

⁠修改代理端口

# 例如代理对外用 3088
docker run -d \
  --name dsh-harness \
  -p 3088:3088 \
  -v dsh-data:/root/.dsh \
  -e PROXY_PORT=3088 \
  --restart unless-stopped \
  smanx/deepseek-harness:latest

⁠数据持久化

DSH 的会话/配置数据保存在容器内 /root/.dsh，上面的命令用命名卷 dsh-data 持久化：

• docker stop/start 和容器删除后卷仍在，数据不丢；
• 彻底清除数据：docker volume rm dsh-data（先停容器）。

⁠停止 / 重启 / 删除

docker stop dsh-harness     # 停止
docker start dsh-harness    # 再次启动
docker logs -f dsh-harness  # 查看日志
docker rm -f dsh-harness    # 删除容器（卷中的数据保留）

⁠联系作者 / 反馈

• 交流与 Bug 反馈：https://github.com/deepseek-ai/deepseek-harness/discussions/1762⁠