容器沙箱执行codebam/dsh-opensandbox

@codebam/dsh-opensandbox

在 OpenSandbox 容器内运行 DeepSeek Harness（dsh）执行世界。

该插件注册了两个 dsh 服务：

| 服务 | 替代项 | 效果 |
| --- | --- | --- |
| ctx.subprocess | @deepseek-ai/dsh-subprocess-local | 命令和 PTY shell 通过 OpenSandbox execd 运行。 |
| ctx.sandbox | @deepseek-ai/dsh-sandbox-local | 向 dsh 内置的沙箱感知消费者报告容器世界的隔离事实。 |

由于 ctx.subprocess 是共享的执行接缝，以下现有的 dsh 插件无需修改代码即可在容器世界上继续工作：

- @deepseek-ai/dsh-bash-sandbox — 面向模型的 bash 工具
- @deepseek-ai/dsh-terminal-bash — 持久 PTY 会话（bash）
- @deepseek-ai/dsh-tool-fs-search — grep/glob 在沙箱内运行
- dsh 的权限/提权流程和 sandbox:policy 上下文

配置的工作区以相同的绝对路径绑定挂载到沙箱中，因此宿主机的 ctx.fs 提供者和沙箱看到的是相同的文件。在此版本中，ctx.fs 本身仍保留在宿主机侧：容器是命令执行的边界，而不是替代文件系统。

要求

- Node.js >= 20（dsh 捆绑了更新的 Node）。
- 一个可访问的、使用 Docker 运行时的 OpenSandbox 生命周期服务器。
- OpenSandbox 服务器必须将你挂载的宿主机路径加入允许列表。在其 TOML 中：

[storage]
allowed_host_paths = ["/home/your-user", "/persistent", "/tmp", "/nix/store"]

- 沙箱镜像必须包含 /bin/sh 以及一个接受 infinity 的 sleep
（debian:、ubuntu:、python: 及类似镜像均满足）。

已知限制

- spawnTerminal 需要与 execd 建立 WebSocket，因此本插件向生命周期
API 请求每个沙箱的直接发布端点（官方 SDK 默认值，
use_server_proxy=false），而不是通过服务器自身的代理进行路由。
这是有意为之：在官方服务器镜像中，API 代理的 WebSocket 路由
永远无法完成与沙箱的握手，随后在报告该失败时因 websockets API 不匹配而崩溃。
不支持客户端无法直接访问沙箱发布端口的部署。
- ctx.fs 保留在宿主机侧，容器内的隔离就是
容器本身：confine() 对受限模式报告 partial 强制执行，
因为只读/仅工作区语义并未按命令重新表达。
- 挂载的宿主机路径必须由服务器加入允许列表
（[storage] allowed_host_paths）；位于该列表之外的会话 cwd 会在
沙箱创建时失败，而不会回退到宿主机。

安装

npm install @codebam/dsh-opensandbox

dsh 在运行时提供 @deepseek-ai/ 对等包，因此它们被标记为可选，且不会由本包从 npm 获取。

配置 dsh
将插件添加到 dsh 配置文件，并禁用它所替代的两个本地提供程序。配置文件
cordis.patch.yml（例如 $DSH_HOME/profiles/dsh-tui/cordis.patch.yml）如下所示：

- id: subprocess
disabled: true

- id: sandbox
disabled: true

- insert:
- id: opensandbox-world
name: '@codebam/dsh-opensandbox'
config:
连接（或在 dsh 的环境中设置 OPEN_SANDBOX_API_KEY / OPEN_SANDBOX_DOMAIN）。
apiKeyFile: /run/user/1000/opensandbox/api-key
domain: 127.0.0.1:8090

沙箱镜像和工作区。
image: docker.io/library/debian:bookworm-slim
workspaceRoot: /home/your-user/project
extraReadOnlyMounts:
- /nix/store

限制和生命周期。
timeoutSeconds: 43200
cpu: "4"
memory: 8Gi

相对 name 值从 dsh 配置文件的 node_modules 解析，npm install
@codebam/dsh-opensandbox 会将包放置在那里。指向 index.mjs 的绝对路径也可以使用。

配置

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| apiKey | OPEN_SANDBOX_API_KEY | 生命周期/execd API 密钥。 |
| apiKeyFile | OPEN_SANDBOX_API_KEY_FILE | 保存 API 密钥的文件；在启动时读取。 |
| domain | OPEN_SANDBOX_DOMAIN 或 localhost:8080 | 生命周期主机，可选带端口。 |
| protocol | OPEN_SANDBOX_PROTOCOL 或 http | http 或 https。 |
| image | docker.io/library/debian:bookworm-slim | 沙箱镜像 URI。在生产环境中固定摘要。 |
| workspaceRoot | process.cwd() | 以读写方式挂载到相同路径的主机目录。 |
| extraReadOnlyMounts | ["/nix/store"] | 以只读方式挂载到相同路径的额外主机目录。空列表表示使用此默认值，因为加载器会将缺失的可选数组具体化为 []。 |
| timeoutSeconds | 43200 | 沙箱 TTL；服务器最小值为 60。缓存的沙箱在每条命令前都会重新验证，因此被服务器回收的沙箱会被替换，而不会让命令留在已失效的端点上。 |
| requestTimeoutMs | 300000 | 生命周期 HTTP 超时。 |
| sandboxWaitMs | 180000 | 等待新沙箱报告 Running 的最长时间。 |
| commandTimeoutMs | 0（禁用） | 可选的 execd 侧每条命令超时。 |
| cpu / memory | "4" / "8Gi" | 容器资源限制。 |
| home | /root | 容器 HOME。 |
| env | {} | 每条沙箱命令的额外环境变量。优先于 forwardEnv。 |
| forwardEnv | [] | 要转发到沙箱的主机环境变量名（GH_TOKEN、SSH_AUTH_SOCK）。未设置的名称会被跳过，而不是置空。 |

什么在哪里运行

- 每个工作区根目录会惰性创建一个沙箱，并在命令使用它之前针对生命周期服务器重新验证。如果服务器在其 TTL 时将其回收，插件会创建一个替代沙箱，而不是复用已失效的端点。
- 设置、清理和使用情况记录在沙箱元数据（codebam.dsh.workspace）中。
- 容器的 PATH 是宿主 PATH 被限制为挂载使其可见的目录，再加上
/run/current-system/sw/bin、/etc/profiles/per-user/$USER/bin 和 ~/.nix-profile/bin（当
它们存在时）。这个回退很重要，因为由 systemd 用户单元启动的 dsh 会继承 systemd 的最小
PATH，其中完全不包含任何 /nix/store 条目。
- danger-full-access 仍然运行在 OpenSandbox 世界中；该插件永远不会回退到宿主执行。
- 受限模式报告 enforcement: "partial"，因为容器限制了宿主文件的影响，但不会在容器内
重新表达仅工作区/只读语义。宿主侧的 ctx.fs 围栏仍然为模型的文件工具强制执行工作区
写入。
- 只读存储意味着 nix build 无法从沙箱内部添加路径；如果想要容器化构建，还需挂载宿主的
nix/var/nix/daemon-socket（并接受由此授予的权限）。

让沙箱成为可用的工作区

编码代理期望的两项能力属于配置，而非代码：

- 构建需要将宿主的 Nix 客户端配置和守护进程套接字以只读方式挂载（/etc/nix、
/nix/var/nix/daemon-socket）。容器中的 nix 随后会与宿主守护进程通信，由后者拥有存储
并执行构建。挂载该套接字会授予沙箱以你的用户身份构建和添加存储路径的能力。
- 提交和推送需要将 git 配置、GPG 主目录和代理运行时目录以只读方式挂载
（~/.config/git、~/.gnupg、/run/user/$UID/gnupg），将 GIT_CONFIG_GLOBAL 指向一个
沙箱 git 配置，该配置设置 gpg.program 和 core.sshCommand，并转发 SSH_AUTH_SOCK。
只读的 GPG 主目录根本无法签名——gpg 必须写入锁文件——因此 gpg.program 必须是一个包装
器，将密钥环复制到容器中并链接代理套接字；当私钥存放在智能卡上时，私钥本身永远不会进入
沙箱。如果希望 gh 在内部工作，还需转发 GH_TOKEN。

发布

npm run check
npm pack --dry-run
npm publish --access public

包名是带作用域的，且 publishConfig.access 为 public，因此显式标志只是提醒。

开发

npm install
npm run check

没有构建步骤：发布的文件就是 dsh 加载的相同 ESM 文件。

npm test 在一个进程内的模拟 OpenSandbox 服务器上运行模拟 E2E（它断言 execd 请求模式、
SSE 帧格式、元数据标签和 PTY 帧）。它导入 @deepseek-ai/cordis，该模块由 dsh 在运行时提供，
npm 无法获取，因此先将检出指向任意 dsh 安装的模块：

ln -sfn "$DSH_HOME/profiles/node_modules" node_modules   # DSH_HOME 默认为 ~/.dsh
npm test

许可证

MIT

OpenSandbox 和 DeepSeek Harness 是各自拥有独立许可证的独立项目。该插件通过其
HTTP/WebSocket API 与 OpenSandbox 通信，并挂载由 harness 提供的 dsh 能力接缝。