Sandbase Harness

它到底是什么

SandBase Harness 是一个独立的自托管运行时，而不是只给 Harness 做装饰的插件。它的 README 自称「a local-first runtime for AI agents. Sessions, sandboxed tools, memory, credentials, audit trails, and a built-in Console」，并在 Why 一节里写得很直白：它是「that runtime layer — not a visual workflow builder and not another model SDK」。发布在 managed-agents 这个包名下，版本 0.3.8，Apache-2.0 许可，TypeScript 写成。

它通过两个截然不同的面进入你的环境，把它们混为一谈是最容易犯的错。第一面是运行时本体：一个基于 Hono 的 HTTP 服务，带 /v1 API、位于 /dashboard 的本地 Console、CLI、环境存储，以及从 managed-agents/sdk 导出的 TypeScript SDK。第二面是 managed-agents-mcp：一个六工具的 MCP 桥接，以多架构 OCI 镜像发布，对客户端说 stdio，对运行时说 HTTP。DSH 集成属于第二面，只是套了一件 bundle 的外衣——包里声明了 dsh.bundle.patch: ./examples/deepseek-harness/cordis.yml，profile 构建完成后，这个 patch 会「starts the bundled MCP entry over stdio」。此后 DSH 通过原生的 mcp__sandbase__* 工具去驱动远端运行时；README 说它可以「list agents, create and run sessions, inspect results and artifacts, and stop work」。容器里「contains only the MCP bridge; agent sessions and sandbox work remain in the connected Harness runtime」——也就是说，背后没有跑着的运行时，这个桥接是空的。

你要跑什么，东西放在哪

安装走的是 GitHub 上打了 tag 的源码发布：clone v0.3.8 这个 tag、npm ci、npm run build，然后在你自建的工作目录里 init 再 start。该目录里装着 agents/（YAML 定义）、skills/，以及被 gitignore 的 .managed-agents/ 状态目录，其中有 config.yaml、data.db（SQLite 元数据）、日志、上传的文件与 skill 字节、会话工作区快照，以及本地会话沙箱。服务默认绑定 127.0.0.1:3000，可用 --host 与 --port 调整。

有三个依赖关系值得说准。不需要账号，也不需要托管控制面：README 自己的表格承诺「Local-first SQLite and file storage with no required hosted control plane」，配套 Skill 的安装也被描述为「no SandBase account when DSH already provides web/search tools」。SQLite 是默认的元数据存储，文件字节落在本地 artifacts provider，因此无需另起外部数据库。Docker 对沙箱是可选的，对桥接却基本是必需的——Docker 后端环境需要它，而六工具桥接只以容器镜像形式分发，所以走这条路实际等于需要 Docker。Kubernetes 后端还会通过 kubectl exec/cp 调用外部命令。

README 还用加粗的语气警告：npm 上那个没有 scope 的 managed-agents 不是本项目——「Do not run npx managed-agents or npm install managed-agents」。只从 tag 源码发布或已发布的 OCI 镜像安装。

能力分区：哪些已经交付

README 的 feature 列表才是权威清单，它比周边的宣传句要克制得多。按该清单与 API 示例，已经交付的是：

• 会话与环境 —— /v1/agents、/v1/environments、/v1/sessions、/v1/sessions/{id}/messages，以及 /v1/sessions/{id}/events/stream 上可续传的 Server-Sent Events，支持 Last-Event-ID。
• 存储 —— 「SQLite-backed agents, sessions, environments, credential vaults, memory stores, files, skills, and API keys」，文件与 skill 字节「stored in the workspace state directory」。
• 单一模型提供方边界 —— 「One active model provider boundary configured through Settings V2」，可接 OpenAI、Anthropic、MiniMax 或任何 OpenAI 兼容端点。Agent 指定具体模型 ID；工作区配置只负责说明如何连到模型服务。
• 工具治理 —— 「MCP toolsets, permission policies, built-in tools, and skill packages」。文档里的 agent YAML 给出了形状：agent_toolset_20260401 配上 default_config.permission_policy: { type: always_ask }，再加每个工具的 configs。
• 四种沙箱后端 —— 本地进程、Docker 每会话容器、Kubernetes（kubectl exec/cp）、自托管 worker 队列。
• DSH 桥接 —— 六个 MCP stdio 工具，覆盖 agents、sessions、流式回合、artifacts 与取消。
• TypeScript SDK，以及「follows Claude Managed Agents resource shapes」的 /v1 API，因此可以把 Anthropic SDK 直接指向本地运行时。

没有作为正式能力矩阵发布的，是网上被反复引用的那句顺口溜。README 里待审核目录条目引用了一份外部提案（Nexu Harness Engineering Guide issue #70），把本项目描述为「covering sessions, tool governance, approvals, credentials, memory, artifacts, audit/replay, and selectable backends」。那是项目方向第三方目录投递的提案，不是项目自己的规格说明。仓库从未发布审计记录结构、artifact 生命周期，或 memory API 契约。你如果想知道 memory store 到底怎么处理一个值、artifact 的保留策略是什么、审计轨迹究竟记下哪些事件——这份 README 不说。设计之前请去看 docs/ 与源码。

安全模型：以源码自己的说法为准

这一节请当作「边界」来读，而不是「保证」，因为源码本身就是这样表述的。

认证默认关闭。 README 的 Authentication 一节开头就是「Open by default. Authentication activates when at least one API key exists」——通过 MANAGED_AGENTS_API_KEY，或在 POST /v1/api-keys 创建一把受管密钥。此后客户端发送 Authorization: Bearer <key>。桥接容器接受 MANAGED_AGENTS_API_KEY 以对接「an authenticated remote runtime」，而 Agent Plugin「does not store a key in plugin.json, mcp.json, or the installed plugin files」。README 没有说明密钥的作用域、轮换或过期机制。

凭据。 运行时把「credential vaults」存在 SQLite 元数据里，/v1 接口把它们与 agents、sessions 并列。README 关于它们的说明就到这里为止。

隔离程度取决于部署方式，而且源码反复强调这一点。 四种后端并不等价："sandbox_provider": "local" 创建的是工作区下的「local sandboxes」，以操作者自身权限运行；"sandbox_provider": "docker" 才按会话起容器，并可声明镜像、内存与 CPU。README 津津乐道的每一条第三方目录收录都带着同样的限定词——「backend-dependent isolation」「deployment-dependent isolation」「non-universal isolation scope」「explicit deployment/backend limits」。项目自己从未声称隔离是普适的。

审批闸门。 文档化的 agent 定义里出现了 permission_policy: { type: always_ask }，也就是说工具调用可以被人的确认拦住。README 没有列举可用的策略类型，也没有描述 Console 里的审批界面长什么样。

审计轨迹记了什么。 README 给出的具体机制是可续传事件流：带 Last-Event-ID 的 SSE，用于「session replay and debugging」；同时工作区里还留着 logs/runtime.log 与 snapshots/。这条事件流就是你可以重新接上的持久记录。文中没有提到防篡改属性，没有提到保留或导出策略，也没有外部审计系统。它在摘要表格里被写成「audit trails」「audit and replay」，最稳妥的理解是：一个可回放的事件日志。

「本地优先」的具体含义

这里的 local-first 是可以核对的：运行时进程、它的 SQLite 数据库、上传的字节、以及沙箱，全部落在你选定的目录里；quick start 不需要托管控制面，也不需要账号。默认绑定地址是 127.0.0.1，所以除非你传 --host 0.0.0.0 或在前面架反向代理，Console 与 API 并不会暴露出去。

仍然会离开这台机器的，恰好就是你配置的那些：发往你选定模型服务商的 prompt 与补全；你挂到 agent 上的任何 MCP server（文档示例指向 https://mcp.sentry.dev/mcp）；从 GHCR 拉取 OCI 镜像；以及安装与构建期间的 npm、GitHub 流量。README 声明没有第一方遥测、不会 phone home，但它同样没有详细描述对外网络流量。所以请把「local-first」读成「默认情况下你的数据与运行时属于你自己」，而不是「气隙隔离」或「离线可用」的保证。

运行要求

• Node.js 22+，README 如此写明，package.json 的 "engines": { "node": ">=22" } 也印证了这一点。
• npm 10+（Requirements 一节），外加源码 clone 与构建步骤。
• 一个模型服务商 API key —— OpenAI、Anthropic、MiniMax 或任意 OpenAI 兼容端点。没有它，运行时能起来，但没有可思考的东西。
• Docker，可选：Docker 后端沙箱需要它；而六工具 MCP 桥接与 Agent Plugin 路径实际上必需它，两者都固定使用 ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8。
• kubectl：Kubernetes 后端需要；自托管后端则需要一个可达的 worker 队列。
• README 没有给出操作系统限制，没有 Python 要求（运行时是 TypeScript），不需要外部数据库，也不需要托管账号。

已知局限

• npm 包名是个陷阱。 发布包名是 managed-agents，而 README 明确说 npm 上同名包不是本项目，不得安装、不得用 npx 运行。
• 成熟度没有被描述。 版本是 0.3.8。README 记录的是功能与分发方式，而不是稳定性承诺、支持周期，或「哪些仍属临时」的清单。
• 安装有已知摩擦。 git 方式安装 profile 会先失败一次，报 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED，直到你把打印出来的键粘贴进 profile 的 pnpm-workspace.yaml 的 allowBuilds: 下。安装不完整时，Plugin Hub 可能显示 already installed: managed-agents，官方给出了恢复步骤并指向一份已记录的问题。
• 认证在你打开它之前是关的，而密钥生命周期管理没有文档。
• 隔离质量是你自己的部署决定，安全文档到 feature 表格就结束了。
• 桥接只是桥接。 容器里只有那六个 MCP 工具，所以通过它驱动的每个 DSH 会话，都硬依赖运行时的可用性。
• 没有任何独立安全验证被声称。 README 自己的目录条目就写着：收录「not a maintainer review or security certification」，曾请求评测但「no score or certification claimed」，其中一条带「explicit non-certification scope」。
• 它不是 Harness 自有沙箱的替代品。 README 从未这样说过，文中也没有任何地方把这个运行时定位成 DSH 本地文件策略、审批栈或进程行为的替代者。

什么时候用它、什么时候不要用

当你需要 agent 运行在事后可审查、可回放，当会话必须跨重启存活并依靠可续传事件流接回，或者当你想要受控的代码执行、觉得本地进程后端不够、更愿意显式声明 Docker 或 Kubernetes 后端而不是信任环境里的文件系统时，它值得用。它同样适合这样的场景：你想让同一个运行时被多种客户端驱动——本地 Console、TypeScript SDK、指向 /v1 的 Anthropic SDK，以及通过 MCP 接入的 DSH——并且「自托管 + SQLite + 无托管控制面」本身就是你的硬需求。

但不要因为「沙箱」「审计」这两个词听起来像安全姿态就采用它。请把你选定的后端当作真正的边界：用 sandbox_provider: local 时，就当作 agent 会以你的用户身份、在你的工作区某个子目录里运行。不要假设凭据被加密、可轮换或有作用域，也不要把事件流当成防篡改证据。如果你只是零散地用 DSH，不愿意多养一个长期服务、一个 SQLite 数据库，以及一套需要自己维护构建白名单的安装流程，那就跳过它。另外，永远不要从 npm 用 managed-agents 这个裸名安装它。

兼容性说明

DSH 集成是一个 bundle patch，而不只是发现用的元数据；README 也坦承 dsh-plugin 曾被当成纯元数据标签。桥接固定使用镜像 tag 0.3.8，因此只升级一侧属于未经验证的组合。请在脑中保持两个边界独立：DSH 的文件策略、审批与本地沙箱属于 Harness；远端运行时另有自己的一套，需要单独配置。README 还记录了 Codespaces 开发容器路径（会产生 GitHub 计费），以及一篇演示旧版 v0.3.2 的独立 VPS 部署文章。

FAQ

它真的做了沙箱隔离吗？

这不是产品自带的属性。沙箱是一个可选后端，README 对每一条外部描述都加了「backend-dependent」或「deployment-dependent」的限定。用 sandbox_provider: local 时，你得到的是一个工作区目录和你自己的权限；Docker 每会话容器与 Kubernetes 提供更强的边界，但各自带有前置条件。

我的凭据放在 vault 里安全吗？

源码说得不够，无法回答这个问题。运行时把「credential vaults」与 memory store、文件一起存在 SQLite 元数据中，六工具桥接则避免把密钥写进 plugin.json、mcp.json 或已安装的插件文件。但 README 从未说明 vault 中的值是静态加密的，从未描述密钥轮换或作用域，也从未说明一条 vault 条目能触达什么——所以请把它当作密钥存储，而不是加固过的 secrets manager。

我必须跑服务器、装 Docker 或注册账号吗？

不需要账号，也不需要托管控制面；默认元数据存储是你工作区里的 SQLite，因此也不需要数据库服务。但你确实要跑一个服务进程——Console 与 API 在 127.0.0.1:3000——而 Docker 是 Docker 后端沙箱与已发布的六工具桥接镜像所需要的。模型服务商的 API key 是必需的。

哪些是已交付的，哪些只是提案？

按 README 的 feature 列表与 API 示例，已交付的有：sessions、environments、SQLite 元数据与本地 artifacts、credential vaults、memory stores、files、skills、API keys、四种沙箱后端、带权限策略的 MCP toolsets、可续传的 SSE 回放、TypeScript SDK，以及六工具 DSH 桥接。而「sessions, tool governance, approvals, credentials, memory, artifacts, audit/replay, and selectable backends」这句话出自项目投递给外部目录的提案，并非已发布的能力矩阵——所以不要把它读成一份针对仓库别处从未记录过的行为的契约。