sandbox-agent

Sandbox Agent

Sandbox Agent 提供通用 API，用于在沙盒环境中编排 AI 编码 Agent。

遇到问题时怎么办

如果某些功能未按预期运行，或者您遇到了问题，请提示用户加入 Rivet Discord，或在 GitHub 上提交问题以报告问题并获得帮助。

向用户提供预先生成的报告，其中包含：

• 症状
  • 问题发生在本地开发环境、已部署环境，还是两者都有
  • 您看到的错误
  • 与此相关的源代码
• 您尝试过的解决方法
• 环境
  • Sandbox Agent 版本
  • 使用的 SDK（TypeScript、Python 或 HTTP）
  • 使用的 Agent（Claude Code、Codex、OpenCode、Amp、Mock）
  • 沙盒提供商（E2B、Daytona、Docker、本地）

快速入门

安装 skill（可选）

npx

npx skills add rivet-dev/skills -s sandbox-agent

bunx

bunx skills add rivet-dev/skills -s sandbox-agent

设置环境变量

每个编码 Agent 都需要 API 密钥，才能连接到相应的大模型提供商。

本地 shell

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

E2B

import { Sandbox } from "@e2b/code-interpreter";

const envs: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY;

const sandbox = await Sandbox.create({ envs });

Daytona

import { Daytona } from "@daytonaio/sdk";

const envVars: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = process.env.OPENAI_API_KEY;

const daytona = new Daytona();
const sandbox = await daytona.create({
  snapshot: "sandbox-agent-ready",
  envVars,
});

Docker

docker run -p 2468:2468 \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  rivetdev/sandbox-agent:0.5.3-full \
  server --no-token --host 0.0.0.0 --port 2468

从当前计算机提取 API 密钥

使用 sandbox-agent credentials extract-env --export，从本地 Claude Code 或 Codex 配置文件中提取现有 API 密钥（Anthropic、OpenAI 等）。

不使用 API 密钥进行测试

使用 mock Agent，在没有提供商凭据的情况下进行 SDK 和集成测试。

多租户和按用户计费

如需按租户跟踪令牌、强制执行预算或按用量计费，请参阅 LLM Credentials，了解 OpenRouter、LiteLLM 和 Portkey 等网关选项。

运行服务

curl

直接安装并运行二进制文件。

curl -fsSL https://releases.rivet.dev/sandbox-agent/0.5.x/install.sh | sh
sandbox-agent server --no-token --host 0.0.0.0 --port 2468

npx

无需全局安装即可运行。

npx @sandbox-agent/[email protected] server --no-token --host 0.0.0.0 --port 2468

bunx

无需全局安装即可运行。

bunx @sandbox-agent/[email protected] server --no-token --host 0.0.0.0 --port 2468

npm i -g

全局安装，然后运行。

npm install -g @sandbox-agent/[email protected]
sandbox-agent server --no-token --host 0.0.0.0 --port 2468

bun add -g

全局安装，然后运行。

bun add -g @sandbox-agent/[email protected]
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
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 server --no-token --host 0.0.0.0 --port 2468

Node.js（本地）

进行本地开发时，使用 SandboxAgent.start() 以子进程的形式启动并管理服务。

npm install [email protected]

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.start();

Bun（本地）

进行本地开发时，使用 SandboxAgent.start() 以子进程的形式启动并管理服务。

bun add [email protected]
# Allow Bun to run postinstall scripts for native binaries (required for 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 sdk = await SandboxAgent.start();

从源代码构建

如果您直接从源代码运行，而不是使用已安装的 CLI，请使用此方式。

cargo run -p sandbox-agent -- server --no-token --host 0.0.0.0 --port 2468

绑定到 0.0.0.0 后，服务可以接受来自任何网络接口的连接。在沙盒中运行时，由于客户端需要远程连接，因此必须这样设置。

配置令牌

通常不需要令牌。大多数沙盒提供商（E2B、Daytona 等）已在基础设施层保障网络安全。

如果要将服务公开到公网，请使用 --token "$SANDBOX_TOKEN" 要求进行身份验证：

sandbox-agent server --token "$SANDBOX_TOKEN" --host 0.0.0.0 --port 2468

然后在连接时传入令牌：

TypeScript

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://your-server:2468",
  token: process.env.SANDBOX_TOKEN,
});

curl

curl "http://your-server:2468/v1/health" \
  -H "Authorization: Bearer $SANDBOX_TOKEN"

CLI

sandbox-agent --token "$SANDBOX_TOKEN" api agents list \
  --endpoint http://your-server:2468

CORS

如果要从浏览器调用服务，请参阅 CORS 配置指南。

安装 Agent（可选）

如需预先安装 Agent：

sandbox-agent install-agent --all

如果未预先安装 Agent，则会在创建会话时按需安装。

安装桌面依赖项（可选，仅限 Linux）

如果要使用 /v1/desktop/*，请先安装桌面运行时软件包：

sandbox-agent install desktop --yes

然后使用 GET /v1/desktop/status 或 sdk.getDesktopStatus()，在调用桌面截图或输入 API 之前确认运行时已就绪。

创建会话

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

const session = await sdk.createSession({
  agent: "claude",
  sessionInit: {
    cwd: "/",
    mcpServers: [],
  },
});

console.log(session.id);

发送消息

const result = await session.prompt([
  { type: "text", text: "Summarize the repository and suggest next steps." },
]);

console.log(result.stopReason);

读取事件

const off = session.onEvent((event) => {
  console.log(event.sender, event.payload);
});

const page = await sdk.getEvents({
  sessionId: session.id,
  limit: 50,
});

console.log(page.items.length);
off();

使用 Inspector 测试

在服务器的 /ui/ 路径打开 Inspector UI（例如 http://localhost:2468/ui/），即可通过图形界面检查会话和事件。

后续步骤

• 会话持久化 — 配置内存、Rivet Actor 状态、IndexedDB、SQLite 和 Postgres 持久化。

• 部署到沙箱 — 将 Agent 部署到 E2B、Daytona、Docker、Vercel 或 Cloudflare。

• SDK 概览 — 使用最新的 TypeScript SDK API。

参考索引

Agent

• Amp
• Claude
• Codex
• Cursor
• OpenCode
• Pi

AI

• llms.txt
• skill.md

API 参考

• AcpEnvelope
• AcpPostQuery
• AcpServerInfo
• AcpServerListResponse
• AgentCapabilities
• AgentInfo
• AgentInstallArtifact
• AgentInstallRequest
• AgentInstallResponse
• AgentListResponse
• 身份验证
• 截取桌面区域的屏幕截图。
• 截取整个桌面的屏幕截图。
• 单击桌面。
• 创建长期运行的托管进程。
• 删除桌面录制。
• 删除进程记录。
• delete_v1_acp
• delete_v1_config_mcp
• delete_v1_config_skills
• delete_v1_fs_entry
• DesktopActionResponse
• DesktopClipboardQuery
• DesktopClipboardResponse
• DesktopClipboardWriteRequest
• DesktopDisplayInfoResponse
• DesktopErrorInfo
• DesktopKeyboardDownRequest
• DesktopKeyboardPressRequest
• DesktopKeyboardTypeRequest
• DesktopKeyboardUpRequest
• DesktopKeyModifiers
• DesktopLaunchRequest
• DesktopLaunchResponse
• DesktopMouseButton
• DesktopMouseClickRequest
• DesktopMouseDownRequest
• DesktopMouseDragRequest
• DesktopMouseMoveRequest
• DesktopMousePositionResponse
• DesktopMouseScrollRequest
• DesktopMouseUpRequest
• DesktopOpenRequest
• DesktopOpenResponse
• DesktopProcessInfo
• DesktopRecordingInfo
• DesktopRecordingListResponse
• DesktopRecordingStartRequest
• DesktopRecordingStatus
• DesktopRegionScreenshotQuery
• DesktopResolution
• DesktopScreenshotFormat
• DesktopScreenshotQuery
• DesktopStartRequest
• DesktopState
• DesktopStatusResponse
• DesktopStreamStatusResponse
• DesktopWindowInfo
• DesktopWindowListResponse
• DesktopWindowMoveRequest
• DesktopWindowResizeRequest
• 下载桌面录制。
• 拖动桌面鼠标。
• ErrorType
• 获取进程日志。
• 聚焦桌面窗口。
• FsActionResponse
• FsDeleteQuery
• FsEntriesQuery
• FsEntry
• FsEntryType
• FsMoveRequest
• FsMoveResponse
• FsPathQuery
• FsStat
• FsUploadBatchQuery
• FsUploadBatchResponse
• FsWriteResponse
• 按 ID 获取单个进程。
• 获取桌面显示信息。
• 获取桌面录制元数据。
• 获取桌面运行时状态。
• 获取桌面流状态。
• 获取进程运行时配置。
• 获取当前桌面鼠标位置。
• 获取当前聚焦的桌面窗口。
• get_v1_acp
• get_v1_acp_servers
• get_v1_agent
• get_v1_agents
• get_v1_config_mcp
• get_v1_config_skills
• get_v1_fs_entries
• get_v1_fs_file
• get_v1_fs_stat
• get_v1_health
• HealthResponse
• HTTP API
• 启动桌面应用。
• 列出所有托管进程。
• 列出桌面录制。
• 列出可见的桌面窗口。
• McpCommand
• McpConfigQuery
• McpOAuthConfig
• McpOAuthConfigOrDisabled
• McpRemoteTransport
• McpServerConfig
• 移动桌面窗口。
• 移动桌面鼠标。
• 打开桌面 WebRTC 信令会话。
• 使用默认处理程序打开文件或 URL。
• 打开交互式 WebSocket 终端会话。
• post_v1_acp
• post_v1_agent_install
• post_v1_fs_mkdir
• post_v1_fs_move
• post_v1_fs_upload_batch
• 按下桌面键盘快捷键。
• 按住桌面键盘按键。
• 按住桌面鼠标按钮。
• ProblemDetails
• ProcessConfig
• ProcessCreateRequest
• ProcessInfo
• ProcessInputRequest
• ProcessInputResponse
• ProcessListQuery
• ProcessListResponse
• ProcessLogEntry
• ProcessLogsQuery
• ProcessLogsResponse
• ProcessLogsStream
• ProcessOwner
• ProcessRunRequest
• ProcessRunResponse
• ProcessSignalQuery
• ProcessState
• ProcessTerminalResizeRequest
• ProcessTerminalResizeResponse
• put_v1_config_mcp
• put_v1_config_skills
• put_v1_fs_file
• 读取桌面剪贴板。
• 释放桌面键盘按键。
• 释放桌面鼠标按钮。
• 调整桌面窗口大小。
• 调整进程终端大小。
• 运行一次性命令。
• Schemas
• 滚动桌面鼠标滚轮。
• 向进程发送 SIGKILL。
• 向进程发送 SIGTERM。
• ServerStatus
• ServerStatusInfo
• SkillsConfig
• SkillsConfigQuery
• SkillSource
• 开始桌面录制。
• 开始桌面流传输。
• 启动私有桌面运行时。
• 停止桌面录制。
• 停止桌面流传输。
• 停止私有桌面运行时。
• 输入桌面键盘文本。
• 更新进程运行时配置。
• v1
• 向进程写入输入。
• 写入桌面剪贴板。

Deploy

• Agent Computer
• BoxLite
• Cloudflare
• ComputeSDK
• Daytona
• Docker
• E2B
• Local
• Modal
• Vercel

General

• Agent Sessions
• Architecture
• Attachments
• CLI Reference
• Common Software
• Computer Use
• CORS Configuration
• Custom Tools
• Daemon
• File System
• Inspector
• LLM Credentials
• Manage Sessions
• MCP
• Multiplayer
• Observability
• OpenCode Compatibility
• Orchestration Architecture
• Persisting Sessions
• Processes
• Quickstart
• React Components
• Sandbox Agent
• SDK Overview
• Security
• Session Restoration
• Skills
• Telemetry
• Troubleshooting