SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-10-18

如何自托管 SandBase 代理运行时 (Harness v0.3.8)

在您的 VPS 上部署 SandBase Harness v0.3.8。本指南涵盖 Node.js 22 环境配置、代理 YAML 设置、MCP 服务器集成及通过 Anthropic SDK 调用本地 API 的完整步骤。确保数据安全并完全掌控您的代理运行时环境。

自托管 SandBase 代理运行时的优势

自托管 SandBase 代理运行时意味着在您拥有的服务器上运行 SandBase Harness,从而确保会话、凭据、内存和审计追踪数据存储在您的磁盘上,而非第三方服务器。它是一个 Node 服务。它监听 127.0.0.1:3000,提供 /v1 HTTP API 和 Web 控制台,并将状态保存在与代理文件同目录下的 SQLite 数据库中。

/v1 API 的设计参考了 Claude Managed Agents (CMA),即托管式代理 API。这使得该运行时在两个方向上都具有实用价值:您可以针对 Anthropic SDK 编写代码,将其 baseURL 指向您自己的服务器,随后再将同一套代码迁移至托管部署环境。

SandBase Harness 本身不包含模型,而是通过调用实现。截至 2026 年 10 月 12 日,它支持 OpenAI、Anthropic、MiniMax 以及兼容 OpenAI 的端点,涵盖了自托管网关和 DeepSeek V4 等提供商。MiniMax 在 v0.3.3 版本中成为一级支持的提供商,并提供全球或中国大陆端点选项。您仍需自行提供 API 密钥,或使用支持 OpenAI API 的本地服务器。

开始前的准备工作

  • 一台运行 Ubuntu 24.04 的 VPS,至少有 2 GB RAM。安装过程中,TypeScript 构建占用的资源最多。
  • Node.js 22 或更高版本,以及 npm 10 或更高版本。这两个版本号是项目明确要求的最低版本。
  • git,以及您计划使用的模型提供商的 API key。
  • Docker;只有需要为每个会话提供容器沙箱时才需要。

Ubuntu 24.04 自带的软件仓库提供 Node 18.19,低于最低要求,因此应改用 NodeSource 提供的 Node。

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -v

node -v 应输出 v22 或更高版本,npm -v 应输出 10 或更高版本。如果 node -v 仍输出 v18.19.1,说明发行版软件包仍已安装,并且在 PATH 中优先被找到。继续之前请先将其删除,因为构建使用的是 shell 找到的 node。

从 v0.3.8 标签安装 SandBase

请从标签安装,不要使用变动的分支。直接克隆 main 会获取一小时前提交的任何代码,下文的配置键可能与之不匹配。v0.3.8 发布于 2026 年 8 月 30 日,是截至 2026 年 10 月 12 日的当前标签,也是项目安装文档中指定的版本。

sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build

请使用 npm ci,不要使用 npm install。ci 会安装锁文件中记录的精确版本,确保你的代码树与维护者测试的版本一致。npm install 允许解析更新的版本,这会导致锁定的标签失效。

现在创建工作区。工作区是一个独立的目录,用于存放代理文件和所有运行时状态。将其保留在源码目录之外,意味着你可以拉取更新的标签而不会影响数据。

mkdir -p /opt/sandbase/workspace
cd /opt/sandbase/workspace
node /opt/sandbase/sandbase-harness/dist/index.js init
node /opt/sandbase/sandbase-harness/dist/index.js start

init 会在工作区中写入一个 .managed-agents/ 目录。start 会启动控制台(地址为 http://127.0.0.1:3000/dashboard)和 API(地址为 http://127.0.0.1:3000/v1)。此时从你的笔记本电脑尚无法访问它们,这是正常的,下文将详细说明。目前请通过 SSH 访问控制台:

ssh -N -L 3000:127.0.0.1:3000 you@your-server

那个冗长的 node .../dist/index.js 路径输入起来很麻烦,请给它起个别名。

alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'

下文中的命令均基于此别名编写为 sandbase <command>。

不要从 npm 安装

项目在自己的安装文档中明确说明:npm 上可见的未限定作用域的 managed-agents 软件包并不属于该项目。因此,npx managed-agents 和 npm install -g managed-agents 获取的不是您需要的运行时。维护者正式发布带作用域的软件包前,请从 GitHub 上带标签的源代码安装。这个问题并非项目历史中的小注释:v0.3.1 的主要目的就是用固定标签的源代码安装路径替代旧的 npm 快速入门。

将工作区指向模型提供商

init 写入 .managed-agents/config.yaml。整个工作区只配置一个提供商,各个代理随后选择具体的模型 ID。

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}
storage:
  metadata:
    provider: sqlite
    options: {}
  artifacts:
    provider: local
    options:
      base_path: files

${OPENAI_API_KEY} 表单从进程环境中获取值,因此密钥不会出现在配置文件中,也不会出现在该文件的任何备份中。将它写入仅允许 root 读取的环境文件,因为 systemd 会在降权前以 root 身份读取 EnvironmentFile=。

sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.env

在编辑器中打开该文件,并添加一行 OPENAI_API_KEY=sk-...。提供商密钥应放在这里。代理在会话期间使用的密钥应放在运行时的凭据保管库中。这是另一个问题,影响范围也不同。在将生产令牌粘贴到任一位置之前,建议阅读避免将密钥暴露给 AI 代理。

Agent YAML:mcp_servers、tools 和权限策略

Agent 以 YAML 文件的形式定义在工作区的 agents/ 目录中。这是您实际会花费时间配置的运行时部分。手动编写一个简单的 agent 循环后,这些键的含义会更清晰,因为每个键都对应一项原本需要您自行编写的配置:系统提示词、工具列表,以及工具调用前执行的检查。

name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
metadata:
  template: incident-commander

加载文件并确认已成功导入:

sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"

reload 会将种子 YAML 导入 SQLite。此时 list 应打印出带 ID 的 agent。如果 list 没有显示该 agent,说明文件未被解析,原因会写入 .managed-agents/logs/runtime.log。

mcp_servers 声明 MCP(模型上下文协议)端点。type: url 表示运行时通过 HTTP 与其他位置运行的服务器通信,因此您已经运行的任何服务都可以在这里使用,包括与运行时部署在同一 VPS 上的 MCP 服务器。网页搜索通常是人们首先使用的工具。在接入搜索工具前,建议先阅读 将您自己的 SearXNG 实例交给代理,因为返回陌生人编写页面的工具会将不受信任的文本直接放入模型上下文中。更稳妥的首次接入方式是采用相反的结构:针对您已经拥有的数据提供只读端点。openGym 在训练记录器旁提供了这样的端点,因此代理可以回答有关您训练历史的问题,但无法改写其中任何内容。

声明服务器不会自动将其工具交给 agent。tools 列表负责完成此操作,其中的 mcp_toolset 条目必须将 mcp_server_name 与上方的 name 匹配。如果 agent 的行为表明 MCP 工具不存在,请先逐字符比较这两个字符串,再检查其他位置。

agent_toolset_20260401 是内置工具集。末尾的日期后缀表示架构版本,因此固定使用该版本的 agent 会继续使用其编写时所依赖的工具定义。default_config 为工具集中的所有工具设置策略,configs 下的每个条目则按工具名称覆盖单个工具的策略,例如示例中的 bash。

permission_policy 体现了运行时相较于直接调用模型的价值。always_ask 会暂停会话,等待人工批准后才执行调用。always_allow 则允许调用继续执行。将 bash 设置为 always_ask 后,agent 无法在您看到确切命令之前运行 shell 命令。这与在 VPS 上安全运行 Claude Code时采用的控制方式相同。如果您还运行 DeepSeek Harness,同样的控制会以附加组件的形式提供,而不是作为 YAML 键;限制预算并控制工具调用的插件是与此区块最接近的等效方案。

四种沙盒模式及其适用场景

执行代码的工具调用在沙盒内运行。后端通过环境的 config 对象中的 sandbox_provider 进行选择,或者在控制台的“设置”中,通过“沙盒编辑器”下的“高级”选项设置为工作区默认值。环境通过 POST /v1/environments 的 API 创建。

local 模式

local 模式将代码作为运行时的子进程在宿主机上执行,并使用运行时的用户权限。当环境未指定后端时,该模式为默认选项。若您是唯一用户且 Agent 仅读取您拥有的文件,此模式适用。如果环境指定的后端无法加载,运行时将拒绝执行,而不会静默切换至此模式。此模式不提供隔离。删除文件的工具调用会直接删除您的文件,读取 /etc/sandbase/runtime.env 的工具调用会读取您的提供商密钥。

Docker 容器生命周期管理

Docker 容器在每个会话中仅启动一个容器实例。

{
  "sandbox_provider": "docker",
  "image": "node:22-slim",
  "resources": { "memory": "1g", "cpu": 1 }
}

会话隔离与资源限制

该会话拥有独立的文件系统,且容器会随会话结束而移除。内存和 CPU 上限不属于此模式的默认配置:运行时仅在环境的 resources 代码块中设置了相关参数时,才会向容器添加 --memory 和 --cpus。因此,若环境中未包含该代码块,容器将不会受到资源限制。若省略 image,运行时将使用 ghcr.io/sandbaseai/sandbase-harness-sandbox:latest。当代理程序运行非您编写的代码时,请立即切换至此模式。此方案的代价是运行时用户需要访问 Docker 套接字,而成为 docker 组成员等同于拥有宿主机的 root 权限。按会话创建的容器与 单次运行单容器的自托管代理沙箱 结构相同,因此关于逃逸进程可访问范围的分析在此同样适用。

Kubernetes 运行机制

Kubernetes 将会话工作负载作为 Pod 运行,并使用 kubectl exec 和 kubectl cp 进行驱动。运行时镜像必须包含 kubectl。其 ServiceAccount 需要具备 RBAC(基于角色的访问控制)权限,以便在目标命名空间中创建、删除、获取、列出和监视 Pod,此外还需具备 exec 子资源权限。仅当您已运行集群时,此模式才值得配置。

自托管 Worker

自托管 Worker 在 Settings 中命名为 remote,在 Environment 中命名为 self_hosted。它不会在此机器上运行任何工具代码。运行时会将任务放入队列,外部 Worker 使用 Settings 中提供的 Worker API URL 和密钥,从主机外部获取并完成队列中的任务。当代码需要在不持有提供商密钥的机器上运行时,此方案适用。资源限制仅由 docker 和 kubernetes 执行,因此限制 Worker 的资源占用是 Worker 主机的职责。

为什么运行时绑定到 127.0.0.1?

因为它启动时默认关闭了身份验证。当存在至少一个 API 密钥时,运行时会启用 Bearer Token 身份验证,而全新的 init 不会创建任何密钥。如果在此默认配置下绑定到 0.0.0.0,就会将一个未经验证的代理运行时暴露在公网上,而该运行时拥有 Shell 工具和您的提供商密钥。

因此,当您希望它可被访问时,请保持绑定地址不变,并执行以下两项操作。

首先,开启身份验证。在服务环境变量文件中设置 MANAGED_AGENTS_API_KEY,或使用 POST /v1/api-keys 创建一个密钥,该命令会返回一次 secret_key 字段,之后不再显示。客户端随后需在每个 API 请求中发送 Authorization: Bearer <key>,或将同一密钥作为 x-api-key 发送,但不能同时使用两者。密钥保护的是 API 而非控制台:仪表板页面及其静态资源无需密钥即可加载,/v1/x/health 和 /v1/x/metrics 也是如此。一个密钥代表一个共享身份,因此如果您实际上需要为每个团队成员提供独立的沙盒代理,并将提供商密钥统一保存在网关中,OneCLI 正是为此场景构建的。

其次,在前端部署反向代理并在此处终止 TLS(传输层安全)。运行时设计为提供纯 HTTP 服务,并预期由其他组件处理证书。

server {
    listen 443 ssl;
    server_name agents.example.com;

    ssl_certificate     /etc/letsencrypt/live/agents.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

其中两行配置并非装饰。proxy_buffering off 至关重要,因为会话通过服务器发送事件 (SSE) 流式传输;如果开启缓冲,nginx 会在缓冲区填满前拦截响应,导致控制台在代理工作时显示为空白,直到最后才一次性输出所有内容。proxy_read_timeout 3600s 至关重要,因为默认超时时间为 60 秒,如果数据流静默超过一分钟,代理会在处理过程中断开连接,导致故障表现为运行时崩溃。

在防火墙上,开放 22 和 443 端口。保持 3000 端口关闭,因为代理通过回环地址访问该端口,外部不应直接访问。由于 /v1/x/metrics 无需密钥即可响应,如果您不希望公开运行时指标,请在 server 块中添加 location = /v1/x/metrics { return 404; }。

将 Anthropic SDK 指向您自己的服务器

该运行时实现了一个 CMA 形状的 /v1 接口,因此 Anthropic SDK 客户端只需更改一个字段即可与其通信。

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000'
});

它还接受 Claude Managed Agents 客户端发送的测试版标头,即 anthropic-beta: managed-agents-2026-04-01 和 anthropic-beta: agent-memory-2026-07-22。不带兼容性标头的普通请求会被视为本地调用方。携带 x-api-key、anthropic-version 或 anthropic-beta 的请求将遵循托管规则:必须使用 2023-06-01 版本和 managed-agents 测试版,但 /v1/memory_stores 路由需要 agent-memory 测试版,且拒绝两者同时使用。设置这些标头是为了让为托管部署编写的代码在此处无需修改即可运行。

兼容性接近但并非完全一致。在假设某个接口存在之前,请先阅读检出目录中的 docs/api-matrix.md,因为该项目在其中记录了自身的缺失功能,包括客户端自定义工具,这些工具仍需在当前的事件结果协议之上进行命名注册。

普通 HTTP 请求同样有效,这是验证运行时是否存活的最快方法:

curl -N -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "stream": true}'

正常的响应是一个持续到达的事件流。如果连接中断,请从您看到的最后一个事件处恢复,而不是重放整个轮次:

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: EVENT_ID"

这种可恢复的流正是会话在笔记本电脑合盖后依然存续的原因。事件持久化保存在服务器上,因此客户端是在重放日志,而不是持有唯一副本。

磁盘上凭据、记忆和审计记录的存储位置

运行时管理的所有内容都位于工作区的 .managed-agents/ 下。

.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/
  • data.db 是 SQLite 元数据,包含 agents、sessions、凭据库条目、记忆存储条目和 API keys。
  • files/ 保存上传文件的字节内容,skills/ 保存上传的 skill packages。
  • snapshots/ 保存 session 工作区快照,sandbox/ 保存 local-mode session 的工作目录。
  • logs/runtime.log 是排查某项操作静默无响应时首先应查看的位置。

凭据库由多组机密组成。每组机密都通过一个 auth_type 添加,例如 environment_variable,并在创建 session 时通过 vault_ids 关联到该 session。记忆存储包含命名条目。您可以将这些条目作为 memory_store 挂载到 session,并为其设置独立的访问权限和指令。两者都存储在 data.db 中。这正是它与原始模型调用的区别:运行时会跨 session 保留记忆,并记录发生的情况。

由于所有内容都位于同一个目录中,因此应将整个目录作为一个整体备份。

sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbase

先停止服务。运行时写入 SQLite 数据库时复制数据库,可能会得到一个恢复时无法打开的文件;等到真正需要恢复时才会发现这一点。如果您希望将 agent YAML 保存在 git 中,并将状态数据存放在其他位置,部署文档支持通过 --data-dir 在 start 上固定状态位置。

恢复时执行相反的操作:在新服务器上检出相同的 tag,将归档解压到工作区,然后启动服务。如果您使用了 ${OPENAI_API_KEY} 形式,归档中不会包含 provider key,因此请将其保存在仍可访问的位置。

在 systemd 下运行

为运行时单独创建一个用户。这样,本地沙箱模式下的工具调用就无法以您的身份执行操作。

sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbase

将以下内容保存为 /etc/systemd/system/sandbase.service。

[Unit]
Description=SandBase Harness runtime
After=network-online.target

[Service]
User=sandbase
Group=sandbase
WorkingDirectory=/opt/sandbase/workspace
EnvironmentFile=/etc/sandbase/runtime.env
ExecStart=/usr/bin/node /opt/sandbase/sandbase-harness/dist/index.js start --host 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

项目自带的部署示例会在 PATH 上调用 managed-agents 二进制文件。通过带标签的源代码安装不会创建该文件,因此 ExecStart 会针对构建后的入口点运行 node。

sudo systemctl daemon-reload
sudo systemctl enable --now sandbase
sudo systemctl status sandbase
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/dashboard

正常结果应为 status 返回 active (running),以及 curl 返回 200。如果结果不同,先阅读 journalctl -u sandbase -n 50,再阅读 .managed-agents/logs/runtime.log。enable --now 才是关键部分,因为手动启动的进程会在下一次重启后消失。

故障现象及错误信息

npm run build 被终止且 npm 无报错。 在 1 GB 内存的 VPS 上,TypeScript 编译进程会被内核的 OOM Killer 终止,该行为记录在内核日志中而非 npm 中。使用 journalctl -k | grep -i "out of memory" 进行确认,该命令会输出一行包含被杀掉的 node 进程的信息。请添加 swap 分区,或在更大规格的实例上构建并拷贝 dist/。

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000。 端口已被其他进程占用。使用 sudo ss -lntp | grep 3000 可查看占用进程。请停止该进程,或使用 --port 3001 启动运行时并更新代理配置。

无法从笔记本电脑加载仪表板。 这是预期行为,因为运行时绑定在回环地址上。请使用上述 SSH 隧道,或完成反向代理配置。不要使用 --host 0.0.0.0 进行修复,因为在密钥生成前身份验证功能处于关闭状态。

Docker 沙箱因 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock 失败。 sandbase 用户不在 docker 组中。使用 sudo usermod -aG docker sandbase 修复并重启服务。请注意此操作的权限影响:该组在宿主机上拥有 root 权限,这会抵消为运行时分配独立用户的部分安全初衷。

Kubernetes 沙箱因 Error from server (Forbidden) 失败。 ServiceAccount 缺少 pod 权限或 exec 子资源权限。使用 kubectl auth can-i create pods/exec -n <namespace> 直接检查,该命令会返回 yes 或 no。

添加 API 密钥后 API 请求返回 401。 身份验证在首个密钥生成后自动开启,它覆盖 API 但不覆盖控制台:仪表板页面及其静态资源保持公开,因此控制台可以加载,但在调用 API 时需要密钥。发送 Authorization: Bearer <key> 或 x-api-key: <key>,不要同时发送两者,因为即使在身份验证关闭时,携带两个请求头的请求也会被拒绝并返回 401。如果丢失了密钥,请重新创建一个,因为 secret_key 只在创建时显示一次,且仅以哈希值形式存储。

MCP 服务器的工具在会话中不显示。 核对 mcp_servers 中 name 与 tools 块中的 mcp_server_name 是否一致,然后使用 curl -i <url> 确认服务器本身能否访问该 URL。URL 类型的 MCP 服务器属于网络依赖,VPS 的域名解析和路由策略与你的笔记本电脑不同。

FAQ

我可以在没有 OpenAI 或 Anthropic 密钥的情况下运行 SandBase Harness 吗?

可以,使用 MiniMax 密钥或兼容 OpenAI 的端点即可。运行时支持 OpenAI、Anthropic、MiniMax 以及兼容 OpenAI 的提供商,因此支持 OpenAI API 的本地服务器均可使用。在 .managed-agents/config.yaml 中设置工作区提供商,并将 api_key 及端点指向该地址。运行时本身不包含任何模型,因此必须有外部服务来响应调用。

将运行时暴露在公网端口上安全吗?

默认安装状态下不安全。它默认绑定到 127.0.0.1:3000 且未开启身份验证,仅更改绑定地址无法解决此问题。请创建一个 API 密钥或设置 MANAGED_AGENTS_API_KEY,以启用 API 的 Bearer Token 身份验证。随后在前端部署 nginx 或 Caddy 以实现 TLS 加密,并确保防火墙关闭 3000 端口,仅允许通过代理访问。

本地沙箱、Docker 沙箱和 Kubernetes 沙箱有什么区别?

local 将工具代码作为运行时在宿主机上的子进程运行,使用运行时用户的权限,且无隔离。docker 为每个会话提供独立的容器和文件系统,并在会话结束时销毁;仅当环境的 resources 块中设置了限制时,才会限制内存和 CPU。kubernetes 将会话作为 Pod 运行,并由 kubectl exec 驱动,这需要在运行时镜像内配置 kubectl,并在目标命名空间中配置 Pod 的 RBAC 以及 exec 子资源。第四种后端是自托管工作节点(self-hosted worker),它将任务排队发送给外部工作节点,从而在宿主机之外运行代码。

我具体需要备份什么?

工作区中的 .managed-agents/ 目录。它包含 config.yaml、存储智能体、会话、凭据库条目和记忆条目的 data.db SQLite 数据库,以及上传的文件、技能包和会话快照。备份前请停止服务,以防 SQLite 在归档过程中被写入。作为 ${OPENAI_API_KEY} 引用的提供商 API 密钥不包含在备份中,请另行存储。

为什么要克隆 v0.3.8 标签而不是 main 分支?

标签指向固定的代码树,因此你阅读的配置键和 CLI 命令与你实际获取的版本完全一致。main 会发生变动,且配置键名可能在指南编写与你实际运行之间发生更改。项目方还提醒,npm 上未加作用域的 managed-agents 包并非本项目,因此 npx managed-agents 会安装无关内容。发布 v0.3.1 的主要目的是通过固定的标签源码路径来替代该 npm 快速启动方式。

这篇文章对您有帮助吗?