云端沙箱执行NeevCloudAI/dsh-neev-sandbox

@neevcloud/dsh-sandbox

为你的 DeepSeek Harness agent 在每次运行时提供一个干净、一次性的 Linux 盒子。
这个 bundle 将 Harness 的执行世界——文件、Bash、PTY 和 LSP——迁移到一个短生命周期的、gVisor 隔离的 NeevSandbox 中。
agent 写入的文件和运行的命令共享同一个 sandbox，你的机器上什么都不运行，而且无需 fork：把这个 bundle 放进任何 dsh 安装中，原有工具就能继续工作，只不过现在是在远程执行。

npm install --global @deepseek-ai/dsh
dsh plugin --profile headless add @neevcloud/dsh-sandbox
NEEV_API_KEY=... NEEV_ORG_ID=... NEEV_PROJECT_ID=... \
dsh --profile headless "clone my repo, run the tests, and summarize the failures"

你的 agent 的 pwd、id、它写入的文件、它启动的服务器——全都位于 sandbox 中，而不是你的笔记本电脑上。

为什么

DeepSeek Harness 建立在能力接缝（capability seams）之上：可替换的接口，由 provider 实现，由工具消费。Harness 的 Bash、终端和 LSP 工具将每一个执行世界操作都委托给同一个接缝——ctx.subprocess。
替换这一个 provider，它们就会一起迁移，无需对工具本身做任何改动。这就是这里的全部思路：一个小 bundle，你的 agent 的执行世界就变成了一个远程 sandbox。

遵循 Harness 的 capability-seam
模型，并通过标准的 dsh plugin bundle 机制安装——无需修改 Harness 源码，无需检出 monorepo。

工作原理

三个 Cordis 服务，打包为一个 bundle：

| 入口点 | 注册 | 角色 |
|---|---|---|
| @neevcloud/dsh-sandbox/runtime | ctx.neev | 拥有一个 sandbox：创建 → 就绪 → 退出时删除 |
| @neevcloud/dsh-sandbox/subprocess | ctx.subprocess | 在该 sandbox 中运行进程和 PTY |
| @neevcloud/dsh-sandbox/filesystem | ctx.fs | 在该 sandbox 中读取、写入、编辑和列出文件 |

随附的 cordis.patch.yml 将它们接入：它会禁用本地 subprocess
provider，插入两行 Neev，并将感知沙箱的 Bash 执行器设置为
直接透传。dsh plugin add 会为你应用它。

用例

- 在机器之外运行不受信任或 AI 生成的代码 —— 爆炸半径是一个一次性的
gVisor 沙箱，运行结束后即被删除。
- 每个任务一个全新盒子。 每次 dsh 运行都会获得自己干净的 Linux
环境；没有残留状态，没有“在我笔记本上能跑”。
- 并行展开多个 agent，每个都隔离在自己的沙箱中，彼此不会
干扰对方的文件或进程。
- 可复现、类 CI 的执行，与宿主机上安装了什么无关。
- 长时间运行或交互式工作 —— 开发服务器、REPL 和 TUI 在沙箱内
通过真实 PTY 运行。

安装

npm install --global @deepseek-ai/dsh
dsh plugin --profile headless add @neevcloud/dsh-sandbox

在宿主环境中设置你的 Neev 凭据（切勿提交它们）：

export NEEV_API_KEY=...      # your Neev API key
export NEEV_ORG_ID=...       # organization id
export NEEV_PROJECT_ID=...   # project id

初次使用 NeevCloud？按照 Agentic Studio 快速入门中的
Retrieve organization and project IDs
创建 API key 并找到你的 organization 和 project id。

然后运行一个任务：

dsh --profile headless "use Bash to run 'cat /etc/os-release' and 'id -un', and report the output"

一次成功的运行会报告沙箱的操作系统和用户 —— 而不是你宿主机的 —— 并在
两个生命周期边界处打印沙箱 id：

NeevSandbox created:
NeevSandbox terminated:

随时用 dsh --profile headless --dump-config 验证接线：subprocess 行被
禁用，而 neev-runtime / neev-subprocess 行被插入。

本地开发安装

git clone https://github.com/NeevCloudAI/dsh-neev-sandbox && cd dsh-neev-sandbox
npm install && npm run build
dsh plugin --profile headless add .

配置

runtime 模块接受以下 Cordis 配置字段（均为可选）：

| 字段 | 默认值 | 含义 |
|---|---|---|
| orgId | NEEV_ORG_ID | Organization id |
| projectId | NEEV_PROJECT_ID | Project id |
| templateId | sb-ubuntu-26-04-minimal | 服务器用于预配的沙箱模板 |
| image | — | 显式 OCI 镜像；优先于 templateId |
| cwd | 自动发现 | 绝对工作目录；省略时通过 pwd 发现 |
| persist | — | 一个稳定的沙箱名称。设置后，沙箱会在多次运行间复用（按名称重新连接），并在退出时暂停而非删除，因此其文件得以保留。省略则采用默认的完全临时行为。 |
| idleTimeoutMs | — | 在此空闲时长后自动暂停沙箱以节省成本，并在下一次操作时惰性恢复。省略则永不自动暂停。 |
API 密钥仅从 NEEV_API_KEY 读取——它从来不是配置字段，
因此密钥永远不会出现在已提交的配置文件补丁中，也永远不会
被转发到沙箱中。

覆盖你配置文件的 cordis.patch.yml 中的某一行（补丁会替换整个
配置，因此请重新声明你所需的内容）：

- id: neev-runtime
name: '@neevcloud/dsh-sandbox/runtime'
config:
templateId: sb-ubuntu-26-04-minimal

范围与限制

- 文件版本是派生自元数据的。 SDK 不暴露原生版本
令牌，因此守护 writeText/editText 的新鲜度令牌是
文件 mtime、大小和模式的哈希。守护机制有效；在版本检查与写入之间
存在一个很小的非原子窗口。
- 写入通过临时文件 + 重命名实现原子性，并且在此版本中路径解析
不进行符号链接规范化（realpath）。
- 交互式 stdin 通过终端（PTY）流动；普通受管
进程仅接收启动时的 stdin。
- 环境： 仅转发你显式指定的条目；形似凭据
以及 NEEV_* 的名称始终会被剥离，并且沙箱保留其自身的
基础环境（基础镜像变量无法通过 spawn 环境取消设置）。
- PTY 工作目录和环境 遵循沙箱默认值。

资源

- 创建你的第一个沙箱（Agentic Studio，JS SDK） — 获取 API 密钥以及你的组织/项目 ID
- 沙箱运行时 API 参考 — 此捆绑包所基于的沙箱 API
- AI Agent API 参考 — 代理平台 API
- @neevcloud/sdk — 提供程序所使用的 JavaScript SDK
- DeepSeek Harness 能力接缝 — 此插件所接入的 ctx.subprocess / ctx.fs 模型

常见问题

它会改变我的 Harness 工具吗？ 不会。原装的 Bash、终端和 LSP
工具不受影响——该插件只替换它们所委托的提供程序
（ctx.subprocess 和 ctx.fs），因此所有内容会一次性迁移。

沙箱是如何隔离的？ 每个沙箱都是一个 gVisor（runsc）环境
——一个中介系统调用的用户空间内核，提供类似容器的易用性，
同时具有比共享内核容器更强的边界。

文件和 Bash 会共享状态吗？ 会。它们运行在同一个沙箱中，因此代理
使用其文件工具写入的文件对 Bash 可见，反之亦然。

我的 API 密钥会到达沙箱吗？ 不会。NEEV_API_KEY 仅由
SDK 在主机侧读取；它永远不会被传入沙箱，并且形似凭据的
环境名称会从转发给进程的任何内容中剥离。

沙箱是持久的吗？ 默认情况下，它在启动时创建并在
退出时删除。将 persist 设置为一个稳定的名称，沙箱便会在多次运行之间重新连接
（退出时暂停，下次运行时恢复）且文件保持完整；将
idleTimeoutMs 设置为在空闲时自动暂停以节省成本。

它使用哪个模型？ DeepSeek Harness 配置的任何模型提供商；该插件只提供执行环境，而不提供模型。

开发

npm install
npm run check      # lint · typecheck · test · build
npm pack

实时测试会运行真实的沙箱，并且除非设置了 NEEV_API_KEY（以及 NEEV_ORG_ID / NEEV_PROJECT_ID），否则会自动跳过。两个 Loader 入口点都默认导出其服务类。

若想在不使用 dsh 或模型的情况下自包含地体验这些提供商，请运行
examples/quickstart.mjs —— 它在沙箱中运行一条命令，使用 ctx.fs 写入一个文件，并通过 Bash 将其读回：

npm install && npm run build
NEEV_API_KEY=... NEEV_ORG_ID=... NEEV_PROJECT_ID=... node examples/quickstart.mjs

许可证

Apache 2.0 —— 参见 LICENSE。