sandbox-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sandbox Agent

Sandbox Agent provides a universal API for orchestrating AI coding agents in sandboxed environments.

Sandbox Agent 提供了一个通用API，用于在沙箱环境中编排AI编码代理。

What To Do If You Get Stuck

遇到问题该怎么办

If something is not working as intended or you are stuck, prompt the user to join the Rivet Discord or file an issue on GitHub to report an issue and get help.

Provide the user with a pre-generated report with:

Symptoms
- If this is happening in local dev, deployed, or both
- The error you're seeing
- Relevant source code related to this
What you've tried to solve it
Environment
- Sandbox Agent version
- SDK in use (TypeScript, Python, or HTTP)
- Agent in use (Claude Code, Codex, OpenCode, Amp, Mock)
- Sandbox provider (E2B, Daytona, Docker, local)

如果功能未按预期运行或您遇到瓶颈，请引导用户加入Rivet Discord或在GitHub提交问题以获取帮助。

请为用户提供一份预生成的报告，包含以下内容：

症状
- 问题是出现在本地开发环境、部署环境，还是两者皆有
- 您遇到的错误信息
- 相关的源代码
您已尝试的解决方法
环境信息
- Sandbox Agent版本
- 使用的SDK（TypeScript、Python或HTTP）
- 使用的代理（Claude Code、Codex、OpenCode、Amp、Mock）
- 沙箱提供商（E2B、Daytona、Docker、本地）

Quickstart

快速开始

Install skill (optional)

安装Skill（可选）

bash

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

bash

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

Set environment variables

设置环境变量

Each coding agent requires API keys to connect to their respective LLM providers.

每个编码代理都需要API密钥来连接对应的大语言模型提供商。

Local shell

本地Shell

bash

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

bash

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

E2B

typescript

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 });

typescript

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

typescript

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,
});

typescript

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

bash

docker run -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  your-image

bash

docker run -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  your-image

Extracting API keys from current machine

从当前机器提取API密钥

Use

sandbox-agent credentials extract-env --export

to extract your existing API keys (Anthropic, OpenAI, etc.) from your existing Claude Code or Codex config files on your machine.

使用

sandbox-agent credentials extract-env --export

从您机器上现有的Claude Code或Codex配置文件中提取已有的API密钥（Anthropic、OpenAI等）。

Testing without API keys

无需API密钥进行测试

If you want to test Sandbox Agent without API keys, use the

mock

agent to test the SDK without any credentials. It simulates agent responses for development and testing.

如果您想在没有API密钥的情况下测试Sandbox Agent，可以使用

mock

代理来测试SDK，无需任何凭据。它会模拟代理响应，用于开发和测试。

Run the server

运行服务器

curl

Install and run the binary directly.

bash

curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

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

bash

curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

npx

Run without installing globally.

bash

npx sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

无需全局安装即可运行。

bash

npx sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

npm i -g

Install globally, then run.

bash

npm install -g @sandbox-agent/cli
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

全局安装后运行。

bash

npm install -g @sandbox-agent/cli
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

Build from source

从源码构建

If you're running from source instead of the installed CLI.

bash

cargo run -p sandbox-agent -- server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

如果您使用源码而非已安装的CLI运行。

bash

cargo run -p sandbox-agent -- server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

TypeScript (local)

TypeScript（本地）

For local development, use

SandboxAgent.start()

to automatically spawn and manage the server as a subprocess.

typescript

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.start();

This installs the binary and starts the server for you. No manual setup required.

对于本地开发，使用

SandboxAgent.start()

自动生成并将服务器作为子进程管理。

typescript

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.start();

这会为您安装二进制文件并启动服务器，无需手动设置。

Running without tokens

无令牌运行

If endpoint is not public, use

--no-token

to disable authentication. Most sandbox providers already secure their networking, so tokens are not required.

如果端点不公开，使用

--no-token

禁用身份验证。大多数沙箱提供商已确保网络安全，因此不需要令牌。

CORS

If you're calling the server from a browser, see the CORS configuration guide.

如果您从浏览器调用服务器，请查看CORS配置指南。

Install agents (optional)

安装代理（可选）

To preinstall agents:

bash

sandbox-agent install-agent claude
sandbox-agent install-agent codex
sandbox-agent install-agent opencode
sandbox-agent install-agent amp

If agents are not installed up front, they will be lazily installed when creating a session. It's recommended to pre-install agents then take a snapshot of the sandbox for faster coldstarts.

要预安装代理：

bash

sandbox-agent install-agent claude
sandbox-agent install-agent codex
sandbox-agent install-agent opencode
sandbox-agent install-agent amp

如果未预先安装代理，它们会在创建会话时自动安装。建议预先安装代理，然后对沙箱进行快照，以加快冷启动速度。

Create a session

创建会话

TypeScript

typescript

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  token: process.env.SANDBOX_TOKEN,
});

await client.createSession("my-session", {
  agent: "claude",
  agentMode: "build",
  permissionMode: "default",
});

typescript

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  token: process.env.SANDBOX_TOKEN,
});

await client.createSession("my-session", {
  agent: "claude",
  agentMode: "build",
  permissionMode: "default",
});

curl

bash

curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"claude","agentMode":"build","permissionMode":"default"}'

bash

curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"claude","agentMode":"build","permissionMode":"default"}'

CLI

bash

sandbox-agent api sessions create my-session \
  --agent claude \
  --endpoint http://127.0.0.1:2468 \
  --token "$SANDBOX_TOKEN"

bash

sandbox-agent api sessions create my-session \
  --agent claude \
  --endpoint http://127.0.0.1:2468 \
  --token "$SANDBOX_TOKEN"

Send a message

发送消息

TypeScript

typescript

await client.postMessage("my-session", {
  message: "Summarize the repository and suggest next steps.",
});

typescript

await client.postMessage("my-session", {
  message: "Summarize the repository and suggest next steps.",
});

curl

bash

curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize the repository and suggest next steps."}'

bash

curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize the repository and suggest next steps."}'

CLI

bash

sandbox-agent api sessions send-message my-session \
  --message "Summarize the repository and suggest next steps." \
  --endpoint http://127.0.0.1:2468 \
  --token "$SANDBOX_TOKEN"

bash

sandbox-agent api sessions send-message my-session \
  --message "Summarize the repository and suggest next steps." \
  --endpoint http://127.0.0.1:2468 \
  --token "$SANDBOX_TOKEN"

Read events

读取事件

TypeScript

typescript

// Poll for events
const events = await client.getEvents("my-session", { offset: 0, limit: 50 });

// Or stream events
for await (const event of client.streamEvents("my-session", { offset: 0 })) {
  console.log(event.type, event.data);
}

typescript

// 轮询事件
const events = await client.getEvents("my-session", { offset: 0, limit: 50 });

// 或流式传输事件
for await (const event of client.streamEvents("my-session", { offset: 0 })) {
  console.log(event.type, event.data);
}

curl

bash

undefined

bash

undefined

Poll for events

轮询事件

curl "http://127.0.0.1:2468/v1/sessions/my-session/events?offset=0&limit=50"
-H "Authorization: Bearer $SANDBOX_TOKEN"

Stream events via SSE

通过SSE流式传输事件

curl "http://127.0.0.1:2468/v1/sessions/my-session/events/sse?offset=0"
-H "Authorization: Bearer $SANDBOX_TOKEN"

Single-turn stream (post message and get streamed response)

单轮流式传输（发送消息并获取流式响应）

curl -N -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages/stream"
-H "Authorization: Bearer $SANDBOX_TOKEN"
-H "Content-Type: application/json"
-d '{"message":"Hello"}'

undefined

curl -N -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages/stream"
-H "Authorization: Bearer $SANDBOX_TOKEN"
-H "Content-Type: application/json"
-d '{"message":"Hello"}'

undefined

CLI

bash

undefined

bash

undefined

Poll for events

轮询事件

sandbox-agent api sessions events my-session
--endpoint http://127.0.0.1:2468
--token "$SANDBOX_TOKEN"

Stream events via SSE

通过SSE流式传输事件

sandbox-agent api sessions events-sse my-session
--endpoint http://127.0.0.1:2468
--token "$SANDBOX_TOKEN"

Single-turn stream

单轮流式传输

sandbox-agent api sessions send-message-stream my-session
--message "Hello"
--endpoint http://127.0.0.1:2468
--token "$SANDBOX_TOKEN"

undefined

sandbox-agent api sessions send-message-stream my-session
--message "Hello"
--endpoint http://127.0.0.1:2468
--token "$SANDBOX_TOKEN"

undefined

Test with Inspector

使用Inspector测试

Open the Inspector UI to inspect session state using a GUI.

打开Inspector UI，通过GUI查看会话状态。

Next steps

后续步骤

Build a Chat UI — Learn how to build a chat interface for your agent.
Manage Sessions — Persist and replay agent transcripts.
Deploy to a Sandbox — Deploy your agent to E2B, Daytona, or Vercel Sandboxes.

构建聊天UI — 学习如何为您的代理构建聊天界面。
管理会话 — 持久化并重放代理对话记录。
部署到沙箱 — 将您的代理部署到E2B、Daytona或Vercel沙箱。

Reference Map

参考地图

AI

llms.txt
skill.md

llms.txt
skill.md

Deploy

部署

Daytona
Deploy
Docker
E2B
Local

Daytona
Deploy
Docker
E2B
Local

General

通用

Agent Compatibility
Building a Chat UI
CLI Reference
Conversion
CORS Configuration
Inspector
Manage Sessions
Quickstart
Telemetry
Troubleshooting
Universal Schema

Agent Compatibility
Building a Chat UI
CLI Reference
Conversion
CORS Configuration
Inspector
Manage Sessions
Quickstart
Telemetry
Troubleshooting
Universal Schema

SDKs

Python
TypeScript

Python
TypeScript