一个在沙箱内运行的服务器。你的应用程序远程连接，控制 Claude Code、Codex、OpenCode、Cursor、Amp 或 Pi —— 流式传输事件、处理权限、管理会话。
实验性： Gigacode —— 使用任意编码代理的 OpenCode TUI。
远程运行编码代理很困难。现有的 SDK 假定在本地执行，SSH 破坏了 TTY 处理和流式传输，而且每个代理都有不同的 API。从头开始构建意味着要为每个编码代理重新实现一切。
Sandbox Agent 解决了三个问题：
编码代理需要沙箱 —— 你不能让 AI 在生产服务器上执行任意代码。编码代理需要隔离的环境，但现有的 SDK 假定在本地执行。Sandbox Agent 是一个在沙箱内运行并通过 HTTP/SSE 暴露接口的服务器。
每个编码代理都不同 —— Claude Code、Codex、OpenCode、Cursor、Amp 和 Pi 各自拥有专有的 API、事件格式和行为。切换代理意味着重写你的集成代码。Sandbox Agent 提供了一个统一的 HTTP API —— 只需编写一次代码，通过配置更改即可切换代理。
会话是短暂的 —— 代理的转录数据保存在沙箱中。当进程结束时，你会丢失所有内容。Sandbox Agent 以通用模式流式传输事件到你的存储中。持久化到 Postgres、ClickHouse 或 Rivet。以后可以重放，审计所有内容。
Sandbox Agent 充当你的客户端应用程序与各种编码代理之间的通用适配器。每个代理都有自己的适配器，负责在通用 API 和代理特定接口之间进行转换。
选择适合你使用场景的安装方法。
使用以下命令安装 skill：
npx skills add rivet-dev/skills -s sandbox-agent
bunx skills add rivet-dev/skills -s sandbox-agent
将 SDK 直接导入你的 Node 或浏览器应用程序。提供完整的类型安全性和流式支持。
安装
npm install [email protected]
bun add [email protected]
# 可选：允许 Bun 运行 postinstall 脚本以获取原生二进制文件（SandboxAgent.start() 需要）。
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
设置
本地（嵌入模式）：
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.start();
远程（服务器模式）：
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
});
API 概览
const agents = await client.listAgents();
await client.createSession("demo", {
agent: "codex",
agentMode: "default",
});
await client.postMessage("demo", { message: "Hello from the SDK." });
for await (const event of client.streamEvents("demo", { offset: 0 })) {
console.log(event.type, event.data);
}
作为 HTTP 服务器运行，并从任何语言连接。部署到 E2B、Daytona、Vercel 或你自己的基础设施。
# 安装
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
# 运行
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
可选：预安装代理二进制文件（不是必须的；如果你跳过这一步，它们会在首次使用时懒加载）：
sandbox-agent install-agent --all
在本地禁用认证：
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
安装 CLI 包装器（可选但方便）：
npm install -g @sandbox-agent/[email protected]
# 允许 Bun 运行 postinstall 脚本以获取原生二进制文件。
bun add -g @sandbox-agent/[email protected]
bun pm -g trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
创建一个会话并发送消息：
sandbox-agent api sessions create my-session --agent codex --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message-stream my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
你也可以像这样使用 npx：
npx @sandbox-agent/[email protected] --help
bunx @sandbox-agent/[email protected] --help
使用内置的检查器 UI（例如 http://localhost:2468/ui/）调试会话和事件。
通常你需要使用个人 API 令牌在沙箱上测试代理：
sandbox-agent credentials extract-env --export
这会打印你的 OpenAI/Anthropic 等 API 密钥的环境变量，以便与 Sandbox Agent SDK 一起测试。
不，它们是互补的。AI SDK 用于构建聊天界面和调用 LLM。这个 SDK 用于控制能够编写代码和运行命令的自主编码代理。使用 AI SDK 构建你的 UI，当你需要代理实际编码时使用这个 SDK。
Claude Code、Codex、OpenCode、Cursor、Amp 和 Pi。SDK 将其 API 规范化，因此你可以随意切换它们而无需更改代码。
这个 SDK 不负责持久化会话数据。事件以通用的 JSON 模式流式传输，你可以将其持久化到任何地方。请参阅管理会话了解使用 Postgres 或 Rivet Actors 的模式。
两种方式都可以。在本地进行开发，部署到 E2B、Daytona 或 Vercel Sandboxes 用于生产环境。
服务器是一个单一的 Rust 二进制文件，可以通过 curl 安装在任何地方运行。如果你的平台可以运行 Linux 二进制文件（Docker、虚拟机等），它就能工作。请参阅 E2B、Daytona 和 Vercel Sandboxes 的部署指南。
可以。使用 sandbox-agent credentials extract-env 从你的本地代理配置（Claude Code、Codex、OpenCode、Amp、Pi）中提取 API 密钥，并将它们传递给沙箱环境。
Rust 提供了单一的静态二进制文件、快速的启动时间和可预测的内存使用。这使得它无需携带大型运行时（如 Node.js）就能轻松地在沙箱或 CI 中运行。
开发时你可以这样做。但在生产环境中，你需要隔离。编码代理会执行任意代码 —— 这不能在你的服务器上发生。沙箱提供了隔离；这个 SDK 提供了通过 HTTP 远程控制编码代理的 API。
官方 SDK 假定在本地执行。它们会生成进程并期望交互式终端。这个 SDK 在沙箱内运行一个服务器，你通过 HTTP 连接 —— 从一开始就为远程控制而设计。
编码代理期望使用带有正确 TTY 处理的交互式终端。使用管道命令的 SSH 会破坏工具确认、流式输出和人在回路中的流程。SDK 通过一个干净的 HTTP API 处理所有这些。
| 组件 |
|---|
| 描述 |
|---|
| 服务器 | Rust 守护进程 (sandbox-agent server)，暴露 HTTP + SSE API |
| SDK | TypeScript 客户端，支持嵌入模式和服务器模式 |
| 检查器 | 内置 UI，用于检查会话和事件 |
| CLI | sandbox-agent（同一二进制文件，外加 npm 包装器），镜像 HTTP 端点 |