harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 09:01:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: fix bad merge

Browse source
This commit is contained in:
Nathan Flurry 2026-02-11 07:52:48 -08:00
parent 1dd45908a3
commit 94353f7696
205 changed files with 19244 additions and 14866 deletions
Download patch file Download diff file Expand all files Collapse all files

306
docs/agent-sessions.mdx
View file

@ -1,288 +1,90 @@
---
title: "Agent Sessions"
description: "Create sessions and send messages to agents."
description: "Create sessions, prompt agents, and inspect event history."
sidebarTitle: "Sessions"
icon: "comments"
---
Sessions are the unit of interaction with an agent. You create one session per task, then send messages and stream events.
Sessions are the unit of interaction with an agent. Create one session per task, send prompts, and consume event history.
## Session Options
For SDK-based flows, sessions can be restored after runtime/session loss when persistence is enabled.
See [Session Restoration](/session-restoration).
`POST /v1/sessions/{sessionId}` accepts the following fields:
## Create a session
- `agent` (required): `claude`, `codex`, `opencode`, `amp`, or `mock`
- `agentMode`: agent mode string (for example, `build`, `plan`)
- `permissionMode`: permission mode string (`default`, `plan`, `bypass`, etc.)
- `model`: model override (agent-specific)
- `variant`: model variant (agent-specific)
- `agentVersion`: agent version override
- `mcp`: MCP server config map (see `MCP`)
- `skills`: skill path config (see `Skills`)
```ts
import { SandboxAgent } from "sandbox-agent";
## Create A Session
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
});
await client.createSession("build-session", {
const session = await sdk.createSession({
agent: "codex",
agentMode: "build",
permissionMode: "default",
model: "gpt-4.1",
variant: "reasoning",
agentVersion: "latest",
});
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/build-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "codex",
"agentMode": "build",
"permissionMode": "default",
"model": "gpt-4.1",
"variant": "reasoning",
"agentVersion": "latest"
}'
```
</CodeGroup>
## Send A Message
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await client.postMessage("build-session", {
message: "Summarize the repository structure.",
});
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/build-session/messages" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Summarize the repository structure."}'
```
</CodeGroup>
## Stream A Turn
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
const response = await client.postMessageStream("build-session", {
message: "Explain the main entrypoints.",
sessionInit: {
cwd: "/",
mcpServers: [],
},
});
const reader = response.body?.getReader();
if (reader) {
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value, { stream: true }));
}
}
console.log(session.id, session.agentSessionId);
```
```bash cURL
curl -N -X POST "http://127.0.0.1:2468/v1/sessions/build-session/messages/stream" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Explain the main entrypoints."}'
## Send a prompt
```ts
const response = await session.prompt([
{ type: "text", text: "Summarize the repository structure." },
]);
console.log(response.stopReason);
```
</CodeGroup>
## Fetch Events
## Subscribe to live events
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
```ts
const unsubscribe = session.onEvent((event) => {
console.log(event.eventIndex, event.sender, event.payload);
});
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await session.prompt([
{ type: "text", text: "Explain the main entrypoints." },
]);
const events = await client.getEvents("build-session", {
offset: 0,
unsubscribe();
```
## Fetch persisted event history
```ts
const page = await sdk.getEvents({
sessionId: session.id,
limit: 50,
includeRaw: false,
});
console.log(events.events);
```
```bash cURL
curl -X GET "http://127.0.0.1:2468/v1/sessions/build-session/events?offset=0&limit=50" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
</CodeGroup>
`GET /v1/sessions/{sessionId}/get-messages` is an alias for `events`.
## Stream Events (SSE)
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
for await (const event of client.streamEvents("build-session", { offset: 0 })) {
console.log(event.type, event.data);
for (const event of page.items) {
console.log(event.id, event.createdAt, event.sender);
}
```
```bash cURL
curl -N -X GET "http://127.0.0.1:2468/v1/sessions/build-session/events/sse?offset=0" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
</CodeGroup>
## List and load sessions
## List Sessions
```ts
const sessions = await sdk.listSessions({ limit: 20 });
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
for (const item of sessions.items) {
console.log(item.id, item.agent, item.createdAt);
}
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
const sessions = await client.listSessions();
console.log(sessions.sessions);
if (sessions.items.length > 0) {
const loaded = await sdk.resumeSession(sessions.items[0]!.id);
await loaded.prompt([{ type: "text", text: "Continue." }]);
}
```
```bash cURL
curl -X GET "http://127.0.0.1:2468/v1/sessions" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
</CodeGroup>
## Destroy a session
## Reply To A Question
When the agent asks a question, reply with an array of answers. Each inner array is one multi-select response.
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await client.replyQuestion("build-session", "question-1", {
answers: [["yes"]],
});
```ts
await sdk.destroySession(session.id);
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/build-session/questions/question-1/reply" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"answers":[["yes"]]}'
```
</CodeGroup>
## Reject A Question
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await client.rejectQuestion("build-session", "question-1");
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/build-session/questions/question-1/reject" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
</CodeGroup>
## Reply To A Permission Request
Use `once`, `always`, or `reject`.
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await client.replyPermission("build-session", "permission-1", {
reply: "once",
});
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/build-session/permissions/permission-1/reply" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reply":"once"}'
```
</CodeGroup>
## Terminate A Session
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await client.terminateSession("build-session");
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/build-session/terminate" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
</CodeGroup>

64
docs/architecture.mdx Normal file
View file

@ -0,0 +1,64 @@
---
title: "Architecture"
description: "How the client, sandbox, server, and agent fit together."
icon: "microchip"
---
Sandbox Agent runs as an HTTP server inside your sandbox. Your app talks to it remotely.
## Components
- `Your client`: your app code using the `sandbox-agent` SDK.
- `Sandbox`: isolated runtime (E2B, Daytona, Docker, etc.).
- `Sandbox Agent server`: process inside the sandbox exposing HTTP transport.
- `Agent`: Claude/Codex/OpenCode/Amp process managed by Sandbox Agent.
```mermaid placement="top-right"
flowchart LR
CLIENT["Sandbox Agent SDK"]
SERVER["Sandbox Agent server"]
AGENT["Agent process"]
subgraph SANDBOX["Sandbox"]
direction TB
SERVER --> AGENT
end
CLIENT -->|HTTP| SERVER
```
## Suggested Topology
Run the SDK on your backend, then call it from your frontend.
This extra hop is recommended because it keeps auth/token logic on the backend and makes persistence simpler.
```mermaid placement="top-right"
flowchart LR
BROWSER["Browser"]
subgraph BACKEND["Your backend"]
direction TB
SDK["Sandbox Agent SDK"]
end
subgraph SANDBOX_SIMPLE["Sandbox"]
SERVER_SIMPLE["Sandbox Agent server"]
end
BROWSER --> BACKEND
BACKEND --> SDK --> SERVER_SIMPLE
```
### Backend requirements
Your backend layer needs to handle:
- **Long-running connections**: prompts can take minutes.
- **Session affinity**: follow-up messages must reach the same session.
- **State between requests**: session metadata and event history must persist across requests.
- **Graceful recovery**: sessions should resume after backend restarts.
We recommend [Rivet](https://rivet.dev) over serverless because actors natively support the long-lived connections, session routing, and state persistence that agent workloads require.
## Session persistence
For storage driver options and replay behavior, see [Persisting Sessions](/session-persistence).

74
docs/attachments.mdx
View file

@ -1,29 +1,27 @@
---
title: "Attachments"
description: "Upload files into the sandbox and attach them to prompts."
description: "Upload files into the sandbox and reference them in prompts."
sidebarTitle: "Attachments"
icon: "paperclip"
---
Use the filesystem API to upload files, then reference them as attachments when sending prompts.
Use the filesystem API to upload files, then include file references in prompt content.
<Steps>
<Step title="Upload a file">
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
import fs from "node:fs";
const client = new SandboxAgentClient({
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
});
const buffer = await fs.promises.readFile("./data.csv");
const upload = await client.writeFsFile(
{ path: "./uploads/data.csv", sessionId: "my-session" },
const upload = await sdk.writeFsFile(
{ path: "./uploads/data.csv" },
buffer,
);
@ -31,59 +29,33 @@ Use the filesystem API to upload files, then reference them as attachments when
```
```bash cURL
curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=./uploads/data.csv&sessionId=my-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=./uploads/data.csv" \
--data-binary @./data.csv
```
</CodeGroup>
The response returns the absolute path that you should use for attachments.
The upload response returns the absolute path.
</Step>
<Step title="Attach the file in a prompt">
<CodeGroup>
<Step title="Reference the file in a prompt">
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const session = await sdk.createSession({ agent: "mock" });
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await client.postMessage("my-session", {
message: "Please analyze the attached CSV.",
attachments: [
{
path: "/home/sandbox/uploads/data.csv",
mime: "text/csv",
filename: "data.csv",
},
],
});
await session.prompt([
{ type: "text", text: "Please analyze the attached CSV." },
{
type: "resource_link",
name: "data.csv",
uri: "file:///home/sandbox/uploads/data.csv",
mimeType: "text/csv",
},
]);
```
```bash cURL
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": "Please analyze the attached CSV.",
"attachments": [
{
"path": "/home/sandbox/uploads/data.csv",
"mime": "text/csv",
"filename": "data.csv"
}
]
}'
```
</CodeGroup>
</Step>
</Steps>
## Notes
- Use absolute paths from the upload response to avoid ambiguity.
- If `mime` is omitted, the server defaults to `application/octet-stream`.
- OpenCode receives file parts directly; other agents will see the attachment paths appended to the prompt.
- Use absolute file URIs in `resource_link` blocks.
- If `mimeType` is omitted, the agent/runtime may infer a default.
- Support for non-text resources depends on each agent's ACP prompt capabilities.

4
docs/cors.mdx
View file

@ -2,7 +2,6 @@
title: "CORS Configuration"
description: "Configure CORS for browser-based applications."
sidebarTitle: "CORS"
icon: "globe"
---
When calling the Sandbox Agent server from a browser, CORS (Cross-Origin Resource Sharing) controls which origins can make requests.
@ -13,7 +12,6 @@ By default, no CORS origins are allowed. You must explicitly specify origins for
```bash
sandbox-agent server \
--token "$SANDBOX_TOKEN" \
--cors-allow-origin "http://localhost:5173"
```
@ -36,7 +34,6 @@ Specify the flag multiple times to allow multiple origins:
```bash
sandbox-agent server \
--token "$SANDBOX_TOKEN" \
--cors-allow-origin "http://localhost:5173" \
--cors-allow-origin "http://localhost:3000"
```
@ -47,7 +44,6 @@ By default, all methods and headers are allowed. To restrict them:
```bash
sandbox-agent server \
--token "$SANDBOX_TOKEN" \
--cors-allow-origin "https://your-app.com" \
--cors-allow-method "GET" \
--cors-allow-method "POST" \

116
docs/credentials.mdx
View file

@ -1,55 +1,115 @@
---
title: "Credentials"
description: "How sandbox-agent discovers and exposes provider credentials."
icon: "key"
description: "How Sandbox Agent discovers and uses provider credentials."
---
`sandbox-agent` can discover provider credentials from environment variables and local agent config files.
Sandbox Agent discovers API credentials from environment variables and local agent config files.
These credentials are passed through to underlying agent runtimes.
## Supported providers
## Credential sources
- Anthropic
- OpenAI
- Additional provider entries discovered via OpenCode config
Credentials are discovered in priority order.
## Common environment variables
### Environment variables (highest priority)
API keys first:
| Variable | Provider |
| --- | --- |
|----------|----------|
| `ANTHROPIC_API_KEY` | Anthropic |
| `CLAUDE_API_KEY` | Anthropic fallback |
| `OPENAI_API_KEY` | OpenAI |
| `CODEX_API_KEY` | OpenAI fallback |
## Extract credentials (CLI)
OAuth tokens (used when OAuth extraction is enabled):
Show discovered credentials (redacted by default):
| Variable | Provider |
|----------|----------|
| `CLAUDE_CODE_OAUTH_TOKEN` | Anthropic |
| `ANTHROPIC_AUTH_TOKEN` | Anthropic fallback |
```bash
sandbox-agent credentials extract
### Agent config files
| Agent | Config path | Provider |
|-------|-------------|----------|
| Amp | `~/.amp/config.json` | Anthropic |
| Claude Code | `~/.claude.json`, `~/.claude/.credentials.json` | Anthropic |
| Codex | `~/.codex/auth.json` | OpenAI |
| OpenCode | `~/.local/share/opencode/auth.json` | Anthropic/OpenAI |
## Provider requirements by agent
| Agent | Required provider |
|-------|-------------------|
| Claude Code | Anthropic |
| Amp | Anthropic |
| Codex | OpenAI |
| OpenCode | Anthropic or OpenAI |
| Mock | None |
## Error handling behavior
Credential extraction is best-effort:
- Missing or malformed files are skipped.
- Discovery continues to later sources.
- Missing credentials mark providers unavailable instead of failing server startup.
When prompting, Sandbox Agent does not pre-validate provider credentials. Agent-native authentication errors surface through session events/output.
## Checking credential status
### API
`GET /v1/agents` includes `credentialsAvailable` per agent.
```json
{
"agents": [
{
"id": "claude",
"installed": true,
"credentialsAvailable": true
},
{
"id": "codex",
"installed": true,
"credentialsAvailable": false
}
]
}
```
Reveal raw values:
### TypeScript SDK
```bash
sandbox-agent credentials extract --reveal
```typescript
const result = await sdk.listAgents();
for (const agent of result.agents) {
console.log(`${agent.id}: ${agent.credentialsAvailable ? "authenticated" : "no credentials"}`);
}
```
Filter by agent/provider:
## Passing credentials explicitly
Set environment variables before starting Sandbox Agent:
```bash
sandbox-agent credentials extract --agent codex
sandbox-agent credentials extract --provider openai
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
sandbox-agent daemon start
```
Emit shell exports:
Or with SDK-managed local spawn:
```bash
sandbox-agent credentials extract-env --export
```typescript
import { SandboxAgent } from "sandbox-agent";
const sdk = await SandboxAgent.start({
spawn: {
env: {
ANTHROPIC_API_KEY: process.env.MY_ANTHROPIC_KEY,
},
},
});
```
## Notes
- Discovery is best-effort: missing/invalid files do not crash extraction.
- v2 does not expose legacy v1 `credentialsAvailable` agent fields.
- Authentication failures are surfaced by the selected ACP agent process/agent during ACP requests.

312
docs/custom-tools.mdx
View file

@ -5,243 +5,159 @@ sidebarTitle: "Custom Tools"
icon: "wrench"
---
There are two ways to give agents custom tools that run inside the sandbox:
There are two common patterns for sandbox-local custom tooling:
| | MCP Server | Skill |
|---|---|---|
| **How it works** | Sandbox Agent spawns your MCP server process and routes tool calls to it via stdio | A markdown file that instructs the agent to run your script with `node` (or any command) |
| **Tool discovery** | Agent sees tools automatically via MCP protocol | Agent reads instructions from the skill file |
| **Best for** | Structured tools with typed inputs/outputs | Lightweight scripts with natural-language instructions |
| **Requires** | `@modelcontextprotocol/sdk` dependency | Just a markdown file and a script |
| **How it works** | Agent connects to an MCP server (`mcpServers`) | Agent follows `SKILL.md` instructions and runs scripts |
| **Best for** | Typed tool calls and structured protocols | Lightweight task-specific guidance |
| **Requires** | MCP server process (stdio/http/sse) | Script + `SKILL.md` |
Both approaches execute code inside the sandbox, so your tools have full access to the sandbox filesystem, network, and installed system tools.
## Option A: Tools via MCP
## Option A: MCP server (stdio)
<Steps>
<Step title="Write your MCP server">
Create an MCP server that exposes tools using `@modelcontextprotocol/sdk` with `StdioServerTransport`. This server will run inside the sandbox.
<Step title="Write and bundle your MCP server">
```ts src/mcp-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
```ts src/mcp-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "rand",
version: "1.0.0",
});
const server = new McpServer({ name: "rand", version: "1.0.0" });
server.tool(
"random_number",
"Generate a random integer between min and max (inclusive)",
{
min: z.number().describe("Minimum value"),
max: z.number().describe("Maximum value"),
},
async ({ min, max }) => ({
content: [{ type: "text", text: String(Math.floor(Math.random() * (max - min + 1)) + min) }],
}),
);
server.tool(
"random_number",
"Generate a random integer between min and max",
{
min: z.number(),
max: z.number(),
},
async ({ min, max }) => ({
content: [{ type: "text", text: String(Math.floor(Math.random() * (max - min + 1)) + min) }],
}),
);
const transport = new StdioServerTransport();
await server.connect(transport);
```
await server.connect(new StdioServerTransport());
```
This is a simple example. Your MCP server runs inside the sandbox, so you can execute any code you'd like: query databases, call internal APIs, run shell commands, or interact with any service available in the container.
```bash
npx esbuild src/mcp-server.ts --bundle --format=cjs --platform=node --target=node18 --outfile=dist/mcp-server.cjs
```
</Step>
<Step title="Package the MCP server">
Bundle into a single JS file so it can be uploaded and executed without a `node_modules` folder.
<Step title="Upload it into the sandbox">
```bash
npx esbuild src/mcp-server.ts --bundle --format=cjs --platform=node --target=node18 --minify --outfile=dist/mcp-server.cjs
```
```ts
import { SandboxAgent } from "sandbox-agent";
import fs from "node:fs";
This creates `dist/mcp-server.cjs` ready to upload.
const sdk = await SandboxAgent.connect({ baseUrl: "http://127.0.0.1:2468" });
const content = await fs.promises.readFile("./dist/mcp-server.cjs");
await sdk.writeFsFile({ path: "/opt/mcp/custom-tools/mcp-server.cjs" }, content);
```
```bash
curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=/opt/mcp/custom-tools/mcp-server.cjs" \
--data-binary @./dist/mcp-server.cjs
```
</Step>
<Step title="Create sandbox and upload MCP server">
Start your sandbox, then write the bundled file into it.
<Step title="Register MCP config and create a session">
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import fs from "node:fs";
```ts
await sdk.setMcpConfig(
{
directory: "/workspace",
mcpName: "customTools",
},
{
type: "local",
command: "node",
args: ["/opt/mcp/custom-tools/mcp-server.cjs"],
},
);
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
const session = await sdk.createSession({
agent: "claude",
sessionInit: {
cwd: "/workspace",
},
});
const content = await fs.promises.readFile("./dist/mcp-server.cjs");
await client.writeFsFile(
{ path: "/opt/mcp/custom-tools/mcp-server.cjs" },
content,
);
```
```bash cURL
curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=/opt/mcp/custom-tools/mcp-server.cjs" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
--data-binary @./dist/mcp-server.cjs
```
</CodeGroup>
</Step>
<Step title="Create a session">
Point an MCP server config at the bundled JS file. When the session starts, Sandbox Agent spawns the MCP server process and routes tool calls to it.
<CodeGroup>
```ts TypeScript
await client.createSession("custom-tools", {
agent: "claude",
mcp: {
customTools: {
type: "local",
command: ["node", "/opt/mcp/custom-tools/mcp-server.cjs"],
},
},
});
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/custom-tools" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude",
"mcp": {
"customTools": {
"type": "local",
"command": ["node", "/opt/mcp/custom-tools/mcp-server.cjs"]
}
}
}'
```
</CodeGroup>
await session.prompt([
{ type: "text", text: "Use the random_number tool with min=1 and max=10." },
]);
```
</Step>
</Steps>
## Option B: Tools via Skills
Skills are markdown files that instruct the agent how to use a script. Upload the script and a skill file, then point the session at the skill directory.
## Option B: Skills
<Steps>
<Step title="Write your script">
Write a script that the agent will execute. This runs inside the sandbox just like an MCP server, but the agent invokes it directly via its shell tool.
<Step title="Write script + skill file">
```ts src/random-number.ts
const min = Number(process.argv[2]);
const max = Number(process.argv[3]);
```ts src/random-number.ts
const min = Number(process.argv[2]);
const max = Number(process.argv[3]);
if (Number.isNaN(min) || Number.isNaN(max)) {
console.error("Usage: random-number <min> <max>");
process.exit(1);
}
if (Number.isNaN(min) || Number.isNaN(max)) {
console.error("Usage: random-number <min> <max>");
process.exit(1);
}
console.log(Math.floor(Math.random() * (max - min + 1)) + min);
```
console.log(Math.floor(Math.random() * (max - min + 1)) + min);
```
````md SKILL.md
---
name: random-number
description: Generate a random integer between min and max.
---
Run:
```bash
node /opt/skills/random-number/random-number.cjs <min> <max>
```
````
```bash
npx esbuild src/random-number.ts --bundle --format=cjs --platform=node --target=node18 --outfile=dist/random-number.cjs
```
</Step>
<Step title="Write a skill file">
Create a `SKILL.md` that tells the agent what the script does and how to run it. The frontmatter `name` and `description` fields are required. See [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for tips on writing effective skills.
<Step title="Upload files">
```md SKILL.md
---
name: random-number
description: Generate a random integer between min and max (inclusive). Use when the user asks for a random number.
---
```ts
import fs from "node:fs";
To generate a random number, run:
const script = await fs.promises.readFile("./dist/random-number.cjs");
await sdk.writeFsFile({ path: "/opt/skills/random-number/random-number.cjs" }, script);
```bash
node /opt/skills/random-number/random-number.cjs <min> <max>
```
This prints a single random integer between min and max (inclusive).
const skill = await fs.promises.readFile("./SKILL.md");
await sdk.writeFsFile({ path: "/opt/skills/random-number/SKILL.md" }, skill);
```
</Step>
<Step title="Package the script">
Bundle the script just like an MCP server so it has no dependencies at runtime.
<Step title="Use in a session">
```bash
npx esbuild src/random-number.ts --bundle --format=cjs --platform=node --target=node18 --minify --outfile=dist/random-number.cjs
```
</Step>
```ts
const session = await sdk.createSession({
agent: "claude",
sessionInit: {
cwd: "/workspace",
},
});
<Step title="Create sandbox and upload files">
Upload both the bundled script and the skill file.
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import fs from "node:fs";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
const script = await fs.promises.readFile("./dist/random-number.cjs");
await client.writeFsFile(
{ path: "/opt/skills/random-number/random-number.cjs" },
script,
);
const skill = await fs.promises.readFile("./SKILL.md");
await client.writeFsFile(
{ path: "/opt/skills/random-number/SKILL.md" },
skill,
);
```
```bash cURL
curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=/opt/skills/random-number/random-number.cjs" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
--data-binary @./dist/random-number.cjs
curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=/opt/skills/random-number/SKILL.md" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
--data-binary @./SKILL.md
```
</CodeGroup>
</Step>
<Step title="Create a session">
Point the session at the skill directory. The agent reads `SKILL.md` and learns how to use your script.
<CodeGroup>
```ts TypeScript
await client.createSession("custom-tools", {
agent: "claude",
skills: {
sources: [
{ type: "local", source: "/opt/skills/random-number" },
],
},
});
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/custom-tools" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude",
"skills": {
"sources": [
{ "type": "local", "source": "/opt/skills/random-number" }
]
}
}'
```
</CodeGroup>
await session.prompt([
{ type: "text", text: "Use the random-number skill to pick a number from 1 to 100." },
]);
```
</Step>
</Steps>
## Notes
- The sandbox image must include a Node.js runtime that can execute the bundled files.
- The sandbox runtime must include Node.js (or your chosen runtime).
- For persistent skill-source wiring by directory, see [Skills](/skills-config).

71
docs/daemon.mdx
View file

@ -1,96 +1,69 @@
---
title: "Daemon"
description: "Background daemon lifecycle, auto-upgrade, and management."
icon: "microchip"
description: "Background daemon lifecycle and management."
---
The sandbox-agent daemon is a background server process that stays running between sessions. Commands like `sandbox-agent opencode` and `gigacode` automatically start it when needed and restart it when the binary is updated.
The sandbox-agent daemon is a background server process. Commands like `sandbox-agent opencode` and `gigacode` can ensure it is running.
## How it works
1. When you run `sandbox-agent opencode`, `sandbox-agent daemon start`, or `gigacode`, the CLI checks if a daemon is already healthy at the configured host and port.
2. If no daemon is running, one is spawned in the background with stdout/stderr redirected to a log file.
3. The CLI writes a PID file and a build ID file to track the running process and its version.
4. On subsequent invocations, if the daemon is still running but was built from a different commit, the CLI automatically stops the old daemon and starts a new one.
1. A daemon-aware command checks for a healthy daemon at host/port.
2. If missing, it starts one in the background and records PID/version files.
3. Subsequent checks can compare build/version and restart when required.
## Auto-upgrade
## Auto-upgrade behavior
Each build of sandbox-agent embeds a unique **build ID** (the git short hash, or a version-timestamp fallback). When a daemon is started, this build ID is written to a version file alongside the PID file.
On every invocation of `ensure_running` (called by `opencode`, `gigacode`, and `daemon start`), the CLI compares the stored build ID against the current binary's build ID. If they differ, the running daemon is stopped and replaced automatically:
```
daemon outdated (build a1b2c3d -> f4e5d6c), restarting...
```
This means installing a new version of sandbox-agent and running any daemon-aware command is enough to upgrade — no manual restart needed.
- `sandbox-agent opencode` and `gigacode` use ensure-running behavior with upgrade checks.
- `sandbox-agent daemon start` uses direct start by default.
- `sandbox-agent daemon start --upgrade` uses ensure-running behavior (including version check/restart).
## Managing the daemon
### Start
Start a daemon in the background. If one is already running and healthy, this is a no-op.
```bash
sandbox-agent daemon start [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host to bind to |
| `-p, --port <PORT>` | `2468` | Port to bind to |
| `-t, --token <TOKEN>` | - | Authentication token |
| `-n, --no-token` | - | Disable authentication |
| `-H, --host <HOST>` | `127.0.0.1` | Host |
| `-p, --port <PORT>` | `2468` | Port |
| `--upgrade` | false | Use ensure-running + upgrade behavior |
```bash
sandbox-agent daemon start --no-token
sandbox-agent daemon start
sandbox-agent daemon start --upgrade
```
### Stop
Stop a running daemon. Sends SIGTERM and waits up to 5 seconds for a graceful shutdown before falling back to SIGKILL.
```bash
sandbox-agent daemon stop [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
| `-p, --port <PORT>` | `2468` | Port of the daemon |
```bash
sandbox-agent daemon stop
```
| `-H, --host <HOST>` | `127.0.0.1` | Host |
| `-p, --port <PORT>` | `2468` | Port |
### Status
Show whether the daemon is running, its PID, build ID, and log path.
```bash
sandbox-agent daemon status [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
| `-p, --port <PORT>` | `2468` | Port of the daemon |
```bash
sandbox-agent daemon status
# Daemon running (PID 12345, build a1b2c3d, logs: ~/.local/share/sandbox-agent/daemon/daemon-127-0-0-1-2468.log)
```
If the daemon was started with an older binary, the status includes an `[outdated, restart recommended]` notice.
| `-H, --host <HOST>` | `127.0.0.1` | Host |
| `-p, --port <PORT>` | `2468` | Port |
## Files
All daemon state files live under the sandbox-agent data directory (typically `~/.local/share/sandbox-agent/daemon/`):
Daemon state is stored under the sandbox-agent data directory (for example `~/.local/share/sandbox-agent/daemon/`):
| File | Purpose |
|------|---------|
| `daemon-{host}-{port}.pid` | PID of the running daemon process |
| `daemon-{host}-{port}.version` | Build ID of the running daemon |
| `daemon-{host}-{port}.log` | Daemon stdout/stderr log output |
Multiple daemons can run on different host/port combinations without conflicting.
| `daemon-{host}-{port}.pid` | PID of running daemon |
| `daemon-{host}-{port}.version` | Build/version marker |
| `daemon-{host}-{port}.log` | Daemon stdout/stderr log |

191
docs/deploy/cloudflare.mdx
View file

@ -1,21 +1,19 @@
---
title: "Cloudflare"
description: "Deploy the daemon inside a Cloudflare Sandbox."
description: "Deploy Sandbox Agent inside a Cloudflare Sandbox."
---
## Prerequisites
- Cloudflare account with Workers Paid plan
- Docker running locally for `wrangler dev`
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the coding agents
- Cloudflare account with Workers paid plan
- Docker for local `wrangler dev`
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
<Note>
Cloudflare Sandbox SDK is in beta. See [Sandbox SDK docs](https://developers.cloudflare.com/sandbox/) for details.
Cloudflare Sandbox SDK is beta. See [Sandbox SDK docs](https://developers.cloudflare.com/sandbox/).
</Note>
## Quick Start
Create a new Sandbox SDK project:
## Quick start
```bash
npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
@ -24,64 +22,16 @@ cd my-sandbox
## Dockerfile
Create a `Dockerfile` with sandbox-agent and agents pre-installed:
```dockerfile
FROM cloudflare/sandbox:0.7.0
# Install sandbox-agent
RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
RUN sandbox-agent install-agent claude && sandbox-agent install-agent codex
# Pre-install agents
RUN sandbox-agent install-agent claude && \
sandbox-agent install-agent codex
# Required for local development with wrangler dev
EXPOSE 8000
```
<Note>
The `EXPOSE 8000` directive is required for `wrangler dev` to proxy requests to the container. Port 3000 is reserved for the Cloudflare control plane.
</Note>
## Wrangler Configuration
Update `wrangler.jsonc` to use your Dockerfile:
```jsonc
{
"name": "my-sandbox-agent",
"main": "src/index.ts",
"compatibility_date": "2025-01-01",
"compatibility_flags": ["nodejs_compat"],
"containers": [
{
"class_name": "Sandbox",
"image": "./Dockerfile",
"instance_type": "lite",
"max_instances": 1
}
],
"durable_objects": {
"bindings": [
{
"class_name": "Sandbox",
"name": "Sandbox"
}
]
},
"migrations": [
{
"new_sqlite_classes": ["Sandbox"],
"tag": "v1"
}
]
}
```
## TypeScript Example
This example proxies requests to sandbox-agent via `containerFetch`, which works reliably in both local development and production:
## TypeScript proxy example
```typescript
import { getSandbox, type Sandbox } from "@cloudflare/sandbox";
@ -95,158 +45,87 @@ type Env = {
const PORT = 8000;
/** Check if sandbox-agent is already running */
async function isServerRunning(sandbox: Sandbox): Promise<boolean> {
try {
const result = await sandbox.exec(`curl -sf http://localhost:${PORT}/v2/health`);
const result = await sandbox.exec(`curl -sf http://localhost:${PORT}/v1/health`);
return result.success;
} catch {
return false;
}
}
/** Ensure sandbox-agent is running in the container */
async function ensureRunning(sandbox: Sandbox, env: Env): Promise<void> {
if (await isServerRunning(sandbox)) return;
// Set environment variables for agents
const envVars: Record<string, string> = {};
if (env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = env.ANTHROPIC_API_KEY;
if (env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = env.OPENAI_API_KEY;
await sandbox.setEnvVars(envVars);
// Start sandbox-agent server
await sandbox.startProcess(
`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`
);
await sandbox.startProcess(`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`);
// Poll health endpoint until server is ready
for (let i = 0; i < 30; i++) {
if (await isServerRunning(sandbox)) return;
await new Promise((r) => setTimeout(r, 200));
}
throw new Error("sandbox-agent failed to start");
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
// Proxy requests: /sandbox/:name/v2/...
const match = url.pathname.match(/^\/sandbox\/([^/]+)(\/.*)?$/);
if (match) {
const [, name, path = "/"] = match;
const sandbox = getSandbox(env.Sandbox, name);
await ensureRunning(sandbox, env);
// Proxy request to container
return sandbox.containerFetch(
new Request(`http://localhost${path}${url.search}`, request),
PORT
);
if (!match) {
return new Response("Not found", { status: 404 });
}
return new Response("Not found", { status: 404 });
const [, name, path = "/"] = match;
const sandbox = getSandbox(env.Sandbox, name);
await ensureRunning(sandbox, env);
return sandbox.containerFetch(
new Request(`http://localhost${path}${url.search}`, request),
PORT,
);
},
};
```
## Connect from Client
## Connect from a client
```typescript
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
// Connect via the proxy endpoint
const client = new SandboxAgentClient({
const sdk = await SandboxAgent.connect({
baseUrl: "http://localhost:8787/sandbox/my-sandbox",
agent: "mock",
});
// Wait for server to be ready
for (let i = 0; i < 30; i++) {
try {
await client.getHealth();
break;
} catch {
await new Promise((r) => setTimeout(r, 1000));
}
}
const session = await sdk.createSession({ agent: "claude" });
// Create a session and start coding
await client.createSession("my-session", { agent: "claude" });
await client.postMessage("my-session", {
message: "Summarize this repository",
const off = session.onEvent((event) => {
console.log(event.sender, event.payload);
});
for await (const event of client.streamEvents("my-session")) {
// Auto-approve permissions
if (event.type === "permission.requested") {
await client.replyPermission("my-session", event.data.permission_id, {
reply: "once",
});
}
// Handle text output
if (event.type === "item.delta" && event.data?.delta) {
process.stdout.write(event.data.delta);
}
}
await session.prompt([{ type: "text", text: "Summarize this repository" }]);
off();
```
## Environment Variables
Use `.dev.vars` for local development:
```bash
echo "ANTHROPIC_API_KEY=your-api-key" > .dev.vars
```
<Warning>
Use plain `KEY=value` format in `.dev.vars`. Do not use `export KEY=value` - wrangler won't parse the bash syntax.
</Warning>
<Note>
The `.dev.vars` file is automatically gitignored and only used during local development with `npm run dev`.
</Note>
For production, set secrets via wrangler:
```bash
wrangler secret put ANTHROPIC_API_KEY
```
## Local Development
Start the development server:
## Local development
```bash
npm run dev
```
<Note>
First run builds the Docker container (2-3 minutes). Subsequent runs are much faster.
</Note>
Test with curl:
Test health:
```bash
curl http://localhost:8787/sandbox/demo/v2/health
curl http://localhost:8787/sandbox/demo/v1/health
```
<Tip>
Containers cache environment variables. If you change `.dev.vars`, either use a new sandbox name or clear existing containers:
```bash
docker ps -a | grep sandbox | awk '{print $1}' | xargs -r docker rm -f
```
</Tip>
## Production Deployment
Deploy to Cloudflare:
## Production deployment
```bash
wrangler deploy
```
For production with preview URLs (direct container access), you'll need a custom domain with wildcard DNS routing. See [Cloudflare Production Deployment](https://developers.cloudflare.com/sandbox/guides/production-deployment/) for setup instructions.

46
docs/deploy/daytona.mdx
View file

@ -1,63 +1,52 @@
---
title: "Daytona"
description: "Run the daemon in a Daytona workspace."
description: "Run Sandbox Agent in a Daytona workspace."
---
<Warning>
Daytona Tier 3+ is required to access api.anthropic.com and api.openai.com. Tier 1/2 sandboxes have restricted network access that will cause agent failures. See [Daytona network limits](https://www.daytona.io/docs/en/network-limits/) for details.
Daytona Tier 3+ is required for access to common model provider endpoints.
See [Daytona network limits](https://www.daytona.io/docs/en/network-limits/).
</Warning>
## Prerequisites
- `DAYTONA_API_KEY` environment variable
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the coding agents
- `DAYTONA_API_KEY`
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
## TypeScript Example
## TypeScript example
```typescript
import { Daytona } from "@daytonaio/sdk";
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
const daytona = new Daytona();
// Pass API keys to the sandbox
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 sandbox = await daytona.create({ envVars });
// Install sandbox-agent
await sandbox.process.executeCommand(
"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh"
);
// Start the server in the background
await sandbox.process.executeCommand(
"nohup sandbox-agent server --no-token --host 0.0.0.0 --port 3000 >/tmp/sandbox-agent.log 2>&1 &"
);
// Wait for server to be ready
await new Promise((r) => setTimeout(r, 2000));
// Get the public URL
const baseUrl = (await sandbox.getSignedPreviewUrl(3000, 4 * 60 * 60)).url;
const sdk = await SandboxAgent.connect({ baseUrl });
// Connect and use the SDK
const client = new SandboxAgentClient({ baseUrl, agent: "mock" });
const session = await sdk.createSession({ agent: "claude" });
await session.prompt([{ type: "text", text: "Summarize this repository" }]);
await client.createSession("my-session", {
agent: "claude",
permissionMode: "default",
});
// Cleanup when done
await sandbox.delete();
```
## Using Snapshots for Faster Startup
For production, use snapshots with pre-installed binaries:
## Using snapshots for faster startup
```typescript
import { Daytona, Image } from "@daytonaio/sdk";
@ -65,7 +54,6 @@ import { Daytona, Image } from "@daytonaio/sdk";
const daytona = new Daytona();
const SNAPSHOT = "sandbox-agent-ready";
// Create snapshot once (takes 2-3 minutes)
const hasSnapshot = await daytona.snapshot.get(SNAPSHOT).then(() => true, () => false);
if (!hasSnapshot) {
@ -73,18 +61,10 @@ if (!hasSnapshot) {
name: SNAPSHOT,
image: Image.base("ubuntu:22.04").runCommands(
"apt-get update && apt-get install -y curl ca-certificates",
"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh",
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
"sandbox-agent install-agent claude",
"sandbox-agent install-agent codex",
),
});
}
// Now sandboxes start instantly
const sandbox = await daytona.create({
snapshot: SNAPSHOT,
envVars,
});
```
See [Daytona Snapshots](https://daytona.io/docs/snapshots) for details.

34
docs/deploy/docker.mdx
View file

@ -1,15 +1,15 @@
---
title: "Docker"
description: "Build and run the daemon in a Docker container."
description: "Build and run Sandbox Agent in a Docker container."
---
<Warning>
Docker is not recommended for production. Standard Docker containers don't provide sufficient isolation for running untrusted code. Use a dedicated sandbox provider like E2B or Daytona for production workloads.
Docker is not recommended for production isolation of untrusted workloads. Use dedicated sandbox providers (E2B, Daytona, etc.) for stronger isolation.
</Warning>
## Quick Start
## Quick start
Run sandbox-agent in a container with agents pre-installed:
Run Sandbox Agent with agents pre-installed:
```bash
docker run --rm -p 3000:3000 \
@ -17,23 +17,21 @@ docker run --rm -p 3000:3000 \
-e OPENAI_API_KEY="$OPENAI_API_KEY" \
alpine:latest sh -c "\
apk add --no-cache curl ca-certificates libstdc++ libgcc bash && \
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh && \
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh && \
sandbox-agent install-agent claude && \
sandbox-agent install-agent codex && \
sandbox-agent server --no-token --host 0.0.0.0 --port 3000"
```
<Note>
Alpine is required because Claude Code is built for musl libc. Debian/Ubuntu images use glibc and won't work.
Alpine is required for some agent binaries that target musl libc.
</Note>
Access the API at `http://localhost:3000`.
## TypeScript with dockerode
```typescript
import Docker from "dockerode";
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
const docker = new Docker();
const PORT = 3000;
@ -42,7 +40,7 @@ const container = await docker.createContainer({
Image: "alpine:latest",
Cmd: ["sh", "-c", [
"apk add --no-cache curl ca-certificates libstdc++ libgcc bash",
"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh",
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
"sandbox-agent install-agent claude",
"sandbox-agent install-agent codex",
`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`,
@ -60,24 +58,18 @@ const container = await docker.createContainer({
await container.start();
// Wait for server and connect
const baseUrl = `http://127.0.0.1:${PORT}`;
const client = new SandboxAgentClient({ baseUrl, agent: "mock" });
const sdk = await SandboxAgent.connect({ baseUrl });
// Use the client...
await client.createSession("my-session", {
agent: "claude",
permissionMode: "default",
});
const session = await sdk.createSession({ agent: "claude" });
await session.prompt([{ type: "text", text: "Summarize this repository." }]);
```
## Building from Source
To build a static binary for use in minimal containers:
## Building from source
```bash
docker build -f docker/release/linux-x86_64.Dockerfile -t sandbox-agent-build .
docker run --rm -v "$PWD/artifacts:/artifacts" sandbox-agent-build
```
The binary will be at `./artifacts/sandbox-agent-x86_64-unknown-linux-musl`.
Binary output: `./artifacts/sandbox-agent-x86_64-unknown-linux-musl`.

57
docs/deploy/e2b.mdx
View file

@ -1,79 +1,52 @@
---
title: "E2B"
description: "Deploy the daemon inside an E2B sandbox."
description: "Deploy Sandbox Agent inside an E2B sandbox."
---
## Prerequisites
- `E2B_API_KEY` environment variable
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the coding agents
- `E2B_API_KEY`
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
## TypeScript Example
## TypeScript example
```typescript
import { Sandbox } from "@e2b/code-interpreter";
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
// Pass API keys to the sandbox
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({ allowInternetAccess: true, envs });
// Install sandbox-agent
await sandbox.commands.run(
"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh"
);
// Install agents before starting the server
await sandbox.commands.run("sandbox-agent install-agent claude");
await sandbox.commands.run("sandbox-agent install-agent codex");
// Start the server in the background
await sandbox.commands.run(
"sandbox-agent server --no-token --host 0.0.0.0 --port 3000",
{ background: true }
);
// Connect to the server
const baseUrl = `https://${sandbox.getHost(3000)}`;
const client = new SandboxAgentClient({ baseUrl, agent: "mock" });
const sdk = await SandboxAgent.connect({ baseUrl });
// Wait for server to be ready
for (let i = 0; i < 30; i++) {
try {
await client.getHealth();
break;
} catch {
await new Promise((r) => setTimeout(r, 1000));
}
}
// Create a session and start coding
await client.createSession("my-session", {
agent: "claude",
permissionMode: "default",
const session = await sdk.createSession({ agent: "claude" });
const off = session.onEvent((event) => {
console.log(event.sender, event.payload);
});
await client.postMessage("my-session", {
message: "Summarize this repository",
});
await session.prompt([{ type: "text", text: "Summarize this repository" }]);
off();
for await (const event of client.streamEvents("my-session")) {
console.log(event.type, event.data);
}
// Cleanup
await sandbox.kill();
```
## Faster Cold Starts
## Faster cold starts
For faster startup, create a custom E2B template with sandbox-agent and agents pre-installed:
1. Create a template with the install script baked in
2. Pre-install agents: `sandbox-agent install-agent claude codex`
3. Use the template ID when creating sandboxes
See [E2B Custom Templates](https://e2b.dev/docs/sandbox-template) for details.
For faster startup, create a custom E2B template with Sandbox Agent and target agents pre-installed.
See [E2B Custom Templates](https://e2b.dev/docs/sandbox-template).

29
docs/deploy/local.mdx
View file

@ -1,52 +1,53 @@
---
title: "Local"
description: "Run the daemon locally for development."
description: "Run Sandbox Agent locally for development."
---
For local development, you can run the daemon directly on your machine.
For local development, run Sandbox Agent directly on your machine.
## With the CLI
```bash
# Install
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
# Run
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
```
Or with npm or Bun:
Or with npm/Bun:
<Tabs>
<Tab title="npx">
```bash
npx sandbox-agent server --no-token --host 127.0.0.1 --port 2468
npx @sandbox-agent/cli@0.2.x server --no-token --host 127.0.0.1 --port 2468
```
</Tab>
<Tab title="bunx">
```bash
bunx sandbox-agent server --no-token --host 127.0.0.1 --port 2468
bunx @sandbox-agent/cli@0.2.x server --no-token --host 127.0.0.1 --port 2468
```
</Tab>
</Tabs>
## With the TypeScript SDK
The SDK can automatically spawn and manage the server as a subprocess:
The SDK can spawn and manage the server as a subprocess:
```typescript
import { SandboxAgent } from "sandbox-agent";
// Spawns sandbox-agent server as a subprocess
const client = await SandboxAgent.start();
const sdk = await SandboxAgent.start();
await client.createSession("my-session", {
const session = await sdk.createSession({
agent: "claude",
permissionMode: "default",
});
// When done
await client.dispose();
await session.prompt([
{ type: "text", text: "Summarize this repository." },
]);
await sdk.dispose();
```
This installs the binary (if needed) and starts the server on a random available port. No manual setup required.
This starts the server on an available local port and connects automatically.

57
docs/deploy/vercel.mdx
View file

@ -1,47 +1,39 @@
---
title: "Vercel"
description: "Deploy the daemon inside a Vercel Sandbox."
description: "Deploy Sandbox Agent inside a Vercel Sandbox."
---
## Prerequisites
- `VERCEL_OIDC_TOKEN` or `VERCEL_ACCESS_TOKEN` environment variable
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the coding agents
- `VERCEL_OIDC_TOKEN` or `VERCEL_ACCESS_TOKEN`
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
## TypeScript Example
## TypeScript example
```typescript
import { Sandbox } from "@vercel/sandbox";
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
// Pass API keys to the sandbox
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;
// Create sandbox with port 3000 exposed
const sandbox = await Sandbox.create({
runtime: "node24",
ports: [3000],
});
// Helper to run commands
const run = async (cmd: string, args: string[] = []) => {
const result = await sandbox.runCommand({ cmd, args, env: envs });
if (result.exitCode !== 0) {
throw new Error(`Command failed: ${cmd} ${args.join(" ")}`);
}
return result;
};
// Install sandbox-agent
await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"]);
// Install agents before starting the server
await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh"]);
await run("sandbox-agent", ["install-agent", "claude"]);
await run("sandbox-agent", ["install-agent", "codex"]);
// Start the server in the background
await sandbox.runCommand({
cmd: "sandbox-agent",
args: ["server", "--no-token", "--host", "0.0.0.0", "--port", "3000"],
@ -49,43 +41,22 @@ await sandbox.runCommand({
detached: true,
});
// Connect to the server
const baseUrl = sandbox.domain(3000);
const client = new SandboxAgentClient({ baseUrl, agent: "mock" });
const sdk = await SandboxAgent.connect({ baseUrl });
// Wait for server to be ready
for (let i = 0; i < 30; i++) {
try {
await client.getHealth();
break;
} catch {
await new Promise((r) => setTimeout(r, 1000));
}
}
const session = await sdk.createSession({ agent: "claude" });
// Create a session and start coding
await client.createSession("my-session", {
agent: "claude",
permissionMode: "default",
const off = session.onEvent((event) => {
console.log(event.sender, event.payload);
});
await client.postMessage("my-session", {
message: "Summarize this repository",
});
await session.prompt([{ type: "text", text: "Summarize this repository" }]);
off();
for await (const event of client.streamEvents("my-session")) {
console.log(event.type, event.data);
}
// Cleanup
await sandbox.stop();
```
## Authentication
Vercel Sandboxes support two authentication methods:
- **OIDC Token**: Set `VERCEL_OIDC_TOKEN` (recommended for CI/CD)
- **Access Token**: Set `VERCEL_ACCESS_TOKEN` (for local development, run `vercel env pull`)
See [Vercel Sandbox docs](https://vercel.com/docs/functions/sandbox) for details.
Vercel Sandboxes support OIDC token auth (recommended) and access-token auth.
See [Vercel Sandbox docs](https://vercel.com/docs/functions/sandbox).

23
docs/docs.json
View file

@ -50,8 +50,7 @@
"group": "Getting started",
"pages": [
"quickstart",
"building-chat-ui",
"manage-sessions",
"sdk-overview",
{
"group": "Deploy",
"icon": "server",
@ -68,11 +67,7 @@
]
},
{
"group": "SDKs",
"pages": ["sdks/typescript", "sdks/python"]
},
{
"group": "Agent Features",
"group": "Agent",
"pages": [
"agent-sessions",
"attachments",
@ -82,19 +77,24 @@
]
},
{
"group": "Features",
"group": "System",
"pages": ["file-system"]
},
{
"group": "Advanced",
"pages": ["advanced/acp-http-client"]
"group": "Orchestration",
"pages": [
"architecture",
"session-persistence",
"observability",
"multiplayer",
"security"
]
},
{
"group": "Reference",
"pages": [
"cli",
"inspector",
"session-transcript-schema",
"opencode-compatibility",
{
"group": "More",
@ -102,6 +102,7 @@
"credentials",
"daemon",
"cors",
"session-restoration",
"telemetry",
{
"group": "AI",

159
docs/file-system.mdx
View file

@ -5,183 +5,130 @@ sidebarTitle: "File System"
icon: "folder"
---
The filesystem API lets you list, read, write, move, and delete files inside the sandbox, plus upload batches of files via tar archives.
Control operations (`list`, `mkdir`, `move`, `stat`, `delete`) are ACP extensions on `/v2/rpc` and require an active ACP connection in the SDK.
The filesystem API lets you list, read, write, move, and delete files inside the sandbox, plus upload tar archives in batch.
Binary transfer is intentionally a separate HTTP API (not ACP extension methods):
- `GET /v2/fs/file`
- `PUT /v2/fs/file`
- `POST /v2/fs/upload-batch`
Reason: these are host/runtime capabilities implemented by Sandbox Agent for cross-agent-consistent behavior, and they may require streaming very large binary payloads that ACP JSON-RPC is not suited to transport efficiently.
This is intentionally separate from ACP native `fs/read_text_file` and `fs/write_text_file`.
ACP extension variants may exist in parallel for compatibility, but SDK defaults should use the HTTP endpoints above for binary transfer.
## Path Resolution
## Path resolution
- Absolute paths are used as-is.
- Relative paths use the session working directory when `sessionId` is provided.
- Without `sessionId`, relative paths resolve against the server home directory.
- Relative paths cannot contain `..` or absolute prefixes; requests that attempt to escape the root are rejected.
- Relative paths resolve from the server process working directory.
- Requests that attempt to escape allowed roots are rejected by the server.
The session working directory is the server process current working directory at the moment the session is created.
## List Entries
`listFsEntries()` uses ACP extension method `_sandboxagent/fs/list_entries`.
## List entries
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
const client = new SandboxAgentClient({ baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock" });
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
const entries = await client.listFsEntries({
const entries = await sdk.listFsEntries({
path: "./workspace",
sessionId: "my-session",
});
console.log(entries);
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v2/rpc" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "x-acp-connection-id: acp_conn_1" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"_sandboxagent/fs/list_entries","params":{"path":"./workspace","sessionId":"my-session"}}'
curl -X GET "http://127.0.0.1:2468/v1/fs/entries?path=./workspace"
```
</CodeGroup>
## Read And Write Files
## Read and write files
`PUT /v2/fs/file` writes raw bytes. `GET /v2/fs/file` returns raw bytes.
`PUT /v1/fs/file` writes raw bytes. `GET /v1/fs/file` returns raw bytes.
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
const client = new SandboxAgentClient({ baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock" });
await client.writeFsFile({ path: "./notes.txt", sessionId: "my-session" }, "hello");
const bytes = await client.readFsFile({
path: "./notes.txt",
sessionId: "my-session",
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
await sdk.writeFsFile({ path: "./notes.txt" }, "hello");
const bytes = await sdk.readFsFile({ path: "./notes.txt" });
const text = new TextDecoder().decode(bytes);
console.log(text);
```
```bash cURL
curl -X PUT "http://127.0.0.1:2468/v2/fs/file?path=./notes.txt&sessionId=my-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=./notes.txt" \
--data-binary "hello"
curl -X GET "http://127.0.0.1:2468/v2/fs/file?path=./notes.txt&sessionId=my-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
curl -X GET "http://127.0.0.1:2468/v1/fs/file?path=./notes.txt" \
--output ./notes.txt
```
</CodeGroup>
## Create Directories
`mkdirFs()` uses ACP extension method `_sandboxagent/fs/mkdir`.
## Create directories
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
const client = new SandboxAgentClient({ baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock" });
await client.mkdirFs({
path: "./data",
sessionId: "my-session",
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
await sdk.mkdirFs({ path: "./data" });
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v2/rpc" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "x-acp-connection-id: acp_conn_1" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"_sandboxagent/fs/mkdir","params":{"path":"./data","sessionId":"my-session"}}'
curl -X POST "http://127.0.0.1:2468/v1/fs/mkdir?path=./data"
```
</CodeGroup>
## Move, Delete, And Stat
`moveFs()`, `statFs()`, and `deleteFsEntry()` use ACP extension methods (`_sandboxagent/fs/move`, `_sandboxagent/fs/stat`, `_sandboxagent/fs/delete_entry`).
## Move, delete, and stat
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
const client = new SandboxAgentClient({ baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock" });
await client.moveFs(
{ from: "./notes.txt", to: "./notes-old.txt", overwrite: true },
{ sessionId: "my-session" },
);
const stat = await client.statFs({
path: "./notes-old.txt",
sessionId: "my-session",
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
await client.deleteFsEntry({
path: "./notes-old.txt",
sessionId: "my-session",
await sdk.moveFs({
from: "./notes.txt",
to: "./notes-old.txt",
overwrite: true,
});
const stat = await sdk.statFs({ path: "./notes-old.txt" });
await sdk.deleteFsEntry({ path: "./notes-old.txt" });
console.log(stat);
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v2/rpc" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "x-acp-connection-id: acp_conn_1" \
curl -X POST "http://127.0.0.1:2468/v1/fs/move" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"_sandboxagent/fs/move","params":{"from":"./notes.txt","to":"./notes-old.txt","overwrite":true,"sessionId":"my-session"}}'
-d '{"from":"./notes.txt","to":"./notes-old.txt","overwrite":true}'
curl -X POST "http://127.0.0.1:2468/v2/rpc" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "x-acp-connection-id: acp_conn_1" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":4,"method":"_sandboxagent/fs/stat","params":{"path":"./notes-old.txt","sessionId":"my-session"}}'
curl -X GET "http://127.0.0.1:2468/v1/fs/stat?path=./notes-old.txt"
curl -X POST "http://127.0.0.1:2468/v2/rpc" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "x-acp-connection-id: acp_conn_1" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":5,"method":"_sandboxagent/fs/delete_entry","params":{"path":"./notes-old.txt","sessionId":"my-session"}}'
curl -X DELETE "http://127.0.0.1:2468/v1/fs/entry?path=./notes-old.txt"
```
</CodeGroup>
## Batch Upload (Tar)
## Batch upload (tar)
Batch upload accepts `application/x-tar` only and extracts into the destination directory. The response returns absolute paths for extracted files, capped at 1024 entries.
Batch upload accepts `application/x-tar` and extracts into the destination directory.
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
import { SandboxAgent } from "sandbox-agent";
import fs from "node:fs";
import path from "node:path";
import tar from "tar";
const client = new SandboxAgentClient({ baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock" });
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
const archivePath = path.join(process.cwd(), "skills.tar");
await tar.c({
@ -190,9 +137,8 @@ await tar.c({
}, ["."]);
const tarBuffer = await fs.promises.readFile(archivePath);
const result = await client.uploadFsBatch(tarBuffer, {
const result = await sdk.uploadFsBatch(tarBuffer, {
path: "./skills",
sessionId: "my-session",
});
console.log(result);
@ -201,8 +147,7 @@ console.log(result);
```bash cURL
tar -cf skills.tar -C ./skills .
curl -X POST "http://127.0.0.1:2468/v2/fs/upload-batch?path=./skills&sessionId=my-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
curl -X POST "http://127.0.0.1:2468/v1/fs/upload-batch?path=./skills" \
-H "Content-Type: application/x-tar" \
--data-binary @skills.tar
```

149
docs/mcp-config.mdx
View file

@ -5,119 +5,80 @@ sidebarTitle: "MCP"
icon: "plug"
---
MCP (Model Context Protocol) servers extend agents with tools. Sandbox Agent can auto-load MCP servers when a session starts by passing an `mcp` map in the create-session request.
MCP (Model Context Protocol) servers extend agents with tools and external context.
## Session Config
## Configuring MCP servers
The `mcp` field is a map of server name to config. Use `type: "local"` for stdio servers and `type: "remote"` for HTTP/SSE servers:
The HTTP config endpoints let you store/retrieve MCP server configs by directory + name.
<CodeGroup>
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
await client.createSession("claude-mcp", {
agent: "claude",
mcp: {
filesystem: {
type: "local",
command: "my-mcp-server",
args: ["--root", "."],
},
github: {
type: "remote",
url: "https://example.com/mcp",
headers: {
Authorization: "Bearer ${GITHUB_TOKEN}",
},
},
```ts
// Create MCP config
await sdk.setMcpConfig(
{
directory: "/workspace",
mcpName: "github",
},
{
type: "remote",
url: "https://example.com/mcp",
},
);
// Create a session using the configured MCP servers
const session = await sdk.createSession({
agent: "claude",
sessionInit: {
cwd: "/workspace",
},
});
await session.prompt([
{ type: "text", text: "Use available MCP servers to help with this task." },
]);
// List MCP configs
const config = await sdk.getMcpConfig({
directory: "/workspace",
mcpName: "github",
});
console.log(config.type);
// Delete MCP config
await sdk.deleteMcpConfig({
directory: "/workspace",
mcpName: "github",
});
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/claude-mcp" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude",
"mcp": {
"filesystem": {
"type": "local",
"command": "my-mcp-server",
"args": ["--root", "."]
},
"github": {
"type": "remote",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}"
}
}
}
}'
```
## Config fields
</CodeGroup>
## Config Fields
### Local Server
Stdio servers that run inside the sandbox.
### Local server
| Field | Description |
|---|---|
| `type` | `local` |
| `command` | string or array (`["node", "server.js"]`) |
| `args` | array of string arguments |
| `env` | environment variables map |
| `enabled` | enable or disable the server |
| `timeoutMs` | tool timeout override |
| `cwd` | working directory for the MCP process |
| `command` | executable path |
| `args` | array of CLI args |
| `env` | environment variable map |
| `cwd` | working directory |
| `enabled` | enable/disable server |
| `timeoutMs` | timeout override |
```json
{
"type": "local",
"command": ["node", "./mcp/server.js"],
"args": ["--root", "."],
"env": { "LOG_LEVEL": "debug" },
"cwd": "/workspace"
}
```
### Remote Server
HTTP/SSE servers accessed over the network.
### Remote server
| Field | Description |
|---|---|
| `type` | `remote` |
| `url` | MCP server URL |
| `headers` | static headers map |
| `bearerTokenEnvVar` | env var name to inject into `Authorization: Bearer ...` |
| `envHeaders` | map of header name to env var name |
| `oauth` | object with `clientId`, `clientSecret`, `scope`, or `false` to disable |
| `enabled` | enable or disable the server |
| `timeoutMs` | tool timeout override |
| `transport` | `http` or `sse` |
| `headers` | static headers map |
| `bearerTokenEnvVar` | env var name to inject in auth header |
| `envHeaders` | header name to env var map |
| `oauth` | optional OAuth config object |
| `enabled` | enable/disable server |
| `timeoutMs` | timeout override |
```json
{
"type": "remote",
"url": "https://example.com/mcp",
"headers": { "x-client": "sandbox-agent" },
"bearerTokenEnvVar": "MCP_TOKEN",
"transport": "sse"
}
```
## Custom MCP Servers
## Custom MCP servers
To bundle and upload your own MCP server into the sandbox, see [Custom Tools](/custom-tools).

115
docs/multiplayer.mdx Normal file
View file

@ -0,0 +1,115 @@
---
title: "Multiplayer"
description: "Use Rivet Actors to coordinate shared sessions."
icon: "users"
---
For multiplayer orchestration, use [Rivet Actors](https://rivet.dev/docs/actors).
Recommended model:
- One actor per collaborative workspace/thread.
- The actor owns Sandbox Agent session lifecycle and persistence.
- Clients connect to the actor and receive realtime broadcasts.
Use [actor keys](https://rivet.dev/docs/actors/keys) to map each workspace to one actor, [events](https://rivet.dev/docs/actors/events) for realtime updates, and [lifecycle hooks](https://rivet.dev/docs/actors/lifecycle) for cleanup.
## Example
<CodeGroup>
```ts Actor (server)
import { actor, setup } from "rivetkit";
import { SandboxAgent } from "sandbox-agent";
import { RivetSessionPersistDriver, type RivetPersistState } from "@sandbox-agent/persist-rivet";
type WorkspaceState = RivetPersistState & {
sandboxId: string;
baseUrl: string;
};
export const workspace = actor({
createState: async () => {
return {
sandboxId: "sbx_123",
baseUrl: "http://127.0.0.1:2468",
} satisfies Partial<WorkspaceState>;
},
createVars: async (c) => {
const persist = new RivetSessionPersistDriver(c);
const sdk = await SandboxAgent.connect({
baseUrl: c.state.baseUrl,
persist,
});
const session = await sdk.resumeOrCreateSession({ id: "default", agent: "codex" });
const unsubscribe = session.onEvent((event) => {
c.broadcast("session.event", event);
});
return { sdk, session, unsubscribe };
},
actions: {
getSessionInfo: (c) => ({
workspaceId: c.key[0],
sandboxId: c.state.sandboxId,
}),
prompt: async (c, input: { userId: string; text: string }) => {
c.broadcast("chat.user", {
userId: input.userId,
text: input.text,
createdAt: Date.now(),
});
await c.vars.session.prompt([{ type: "text", text: input.text }]);
},
},
onSleep: async (c) => {
c.vars.unsubscribe?.();
await c.vars.sdk.dispose();
},
});
export const registry = setup({
use: { workspace },
});
```
```ts Client (browser)
import { createClient } from "rivetkit/client";
import type { registry } from "./actors";
const client = createClient<typeof registry>({
endpoint: process.env.NEXT_PUBLIC_RIVET_ENDPOINT!,
});
const workspaceId = "workspace-42";
const room = client.workspace.getOrCreate([workspaceId]);
const conn = room.connect();
conn.on("chat.user", (event) => {
console.log("user message", event);
});
conn.on("session.event", (event) => {
console.log("sandbox event", event);
});
await conn.prompt({
userId: "user-123",
text: "Propose a refactor plan for auth middleware.",
});
```
</CodeGroup>
## Notes
- Keep sandbox calls actor-only. Browser clients should not call Sandbox Agent directly.
- Use `@sandbox-agent/persist-rivet` so session history persists in actor state.
- For client connection patterns, see [Rivet JavaScript client](https://rivet.dev/docs/clients/javascript).

64
docs/observability.mdx Normal file
View file

@ -0,0 +1,64 @@
---
title: "Observability"
description: "Track session activity with OpenTelemetry."
icon: "terminal"
---
Use OpenTelemetry to instrument session traffic, then ship telemetry to your collector/backend.
## Common collectors and backends
- [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
- [Jaeger](https://www.jaegertracing.io/)
- [Grafana Tempo](https://grafana.com/oss/tempo/)
- [Honeycomb](https://www.honeycomb.io/)
- [Datadog APM](https://docs.datadoghq.com/tracing/)
## Example: trace a prompt round-trip
Wrap `session.prompt()` in a span to measure the full round-trip, then log individual events as span events.
Assumes your OTEL provider/exporter is already configured.
```ts
import { trace } from "@opentelemetry/api";
import { SandboxAgent } from "sandbox-agent";
const tracer = trace.getTracer("my-app/sandbox-agent");
const sdk = await SandboxAgent.connect({
baseUrl: process.env.SANDBOX_URL!,
});
const session = await sdk.createSession({ agent: "mock" });
// Log each event as an OTEL span event on the active span
const unsubscribe = session.onEvent((event) => {
const activeSpan = trace.getActiveSpan();
if (!activeSpan) return;
activeSpan.addEvent("session.event", {
"sandbox.sender": event.sender,
"sandbox.event_index": event.eventIndex,
});
});
// The span covers the full prompt round-trip
await tracer.startActiveSpan("sandbox_agent.prompt", async (span) => {
span.setAttribute("sandbox.session_id", session.id);
try {
const result = await session.prompt([
{ type: "text", text: "Summarize this repository." },
]);
span.setAttribute("sandbox.stop_reason", result.stopReason);
} catch (error) {
span.recordException(error as Error);
throw error;
} finally {
span.end();
}
});
unsubscribe();
```

1373
docs/openapi.json
View file

File diff suppressed because it is too large Load diff

129
docs/opencode-compatibility.mdx
View file

@ -1,26 +1,125 @@
---
title: "OpenCode Compatibility"
description: "Status of the OpenCode bridge during ACP v2 migration."
description: "Connect OpenCode clients, SDKs, and web UI to Sandbox Agent."
---
OpenCode compatibility is intentionally deferred during ACP core migration.
<Warning>
**Experimental**: OpenCode SDK/UI compatibility may change.
</Warning>
## Current status (v2 core phases)
Sandbox Agent exposes an OpenCode-compatible API at `/opencode`.
- `/opencode/*` routes are disabled.
- `sandbox-agent opencode` returns an explicit disabled error.
- This is expected while ACP runtime, SDK, and inspector migration is completed.
## Why use OpenCode clients with Sandbox Agent?
## Planned re-enable step
- OpenCode CLI (`opencode attach`)
- OpenCode web UI
- OpenCode TypeScript SDK (`@opencode-ai/sdk`)
OpenCode support is restored in a dedicated phase after ACP core is stable:
## Quick start
1. Reintroduce `/opencode/*` routing on top of ACP internals.
2. Add dedicated OpenCode ↔ ACP integration tests.
3. Re-enable OpenCode docs and operational guidance.
### OpenCode CLI / TUI
Track details in:
```bash
sandbox-agent opencode --port 2468 --no-token
```
- `research/acp/spec.md`
- `research/acp/migration-steps.md`
- `research/acp/todo.md`
Or start server + attach manually:
```bash
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode
```
With authentication enabled:
```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode --password "$SANDBOX_TOKEN"
```
### OpenCode web UI
<Steps>
<Step title="Start Sandbox Agent with CORS">
```bash
sandbox-agent server --no-token --host 127.0.0.1 --port 2468 --cors-allow-origin http://127.0.0.1:5173
```
</Step>
<Step title="Run OpenCode web app">
```bash
git clone https://github.com/anomalyco/opencode
cd opencode/packages/app
export VITE_OPENCODE_SERVER_HOST=127.0.0.1
export VITE_OPENCODE_SERVER_PORT=2468
bun install
bun run dev -- --host 127.0.0.1 --port 5173
```
</Step>
<Step title="Open UI">
Visit `http://127.0.0.1:5173/`.
</Step>
</Steps>
### OpenCode SDK
```typescript
import { createOpencodeClient } from "@opencode-ai/sdk";
const client = createOpencodeClient({
baseUrl: "http://localhost:2468/opencode",
});
const session = await client.session.create();
await client.session.promptAsync({
path: { id: session.data.id },
body: {
parts: [{ type: "text", text: "Hello, write a hello world script" }],
},
});
const events = await client.event.subscribe({});
for await (const event of events.stream) {
console.log(event);
}
```
## Notes
- API base path: `/opencode`
- If server auth is enabled, pass bearer auth (or `--password` in OpenCode CLI)
- For browser UIs, configure CORS with `--cors-allow-origin`
- Provider selector currently exposes compatible providers (`mock`, `amp`, `claude`, `codex`)
- Provider/model metadata for compatibility endpoints is normalized and may differ from native OpenCode grouping
- Optional proxy: set `OPENCODE_COMPAT_PROXY_URL` to forward selected endpoints to native OpenCode
## Endpoint coverage
<Accordion title="Endpoint Status Table">
| Endpoint | Status | Notes |
|---|---|---|
| `GET /event` | ✓ | Session/message updates (SSE) |
| `GET /global/event` | ✓ | GlobalEvent-wrapped stream |
| `GET /session` | ✓ | Session list |
| `POST /session` | ✓ | Create session |
| `GET /session/{id}` | ✓ | Session details |
| `POST /session/{id}/message` | ✓ | Send message |
| `GET /session/{id}/message` | ✓ | Session messages |
| `GET /permission` | ✓ | Pending permissions |
| `POST /permission/{id}/reply` | ✓ | Permission reply |
| `GET /question` | ✓ | Pending questions |
| `POST /question/{id}/reply` | ✓ | Question reply |
| `GET /provider` | ✓ | Provider metadata |
| `GET /command` | ↔ | Proxied when `OPENCODE_COMPAT_PROXY_URL` is set; otherwise stub |
| `GET /config` | ↔ | Proxied when set; otherwise stub |
| `PATCH /config` | ↔ | Proxied when set; otherwise local compatibility behavior |
| `GET /global/config` | ↔ | Proxied when set; otherwise stub |
| `PATCH /global/config` | ↔ | Proxied when set; otherwise local compatibility behavior |
| `/tui/*` | ↔ | Proxied when set; otherwise local compatibility behavior |
| `GET /agent` | − | Agent list |
| *other endpoints* | − | Empty/stub responses |
✓ Functional ↔ Proxied optional − Stubbed
</Accordion>

262
docs/quickstart.mdx
View file

@ -68,14 +68,14 @@ icon: "rocket"
</Tab>
</Tabs>
<AccordionGroup>
<Accordion title="Extracting API keys from current machine">
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.
</Accordion>
<Accordion title="Testing without API keys">
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.
</Accordion>
</AccordionGroup>
<AccordionGroup>
<Accordion title="Extracting API keys from current machine">
Use `sandbox-agent credentials extract-env --export` to extract your existing API keys (Anthropic, OpenAI, etc.) from local Claude Code or Codex config files.
</Accordion>
<Accordion title="Testing without API keys">
Use the `mock` agent for SDK and integration testing without provider credentials.
</Accordion>
</AccordionGroup>
</Step>
<Step title="Run the server">
@ -84,7 +84,7 @@ icon: "rocket"
Install and run the binary directly.
```bash
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
```
</Tab>
@ -93,7 +93,7 @@ icon: "rocket"
Run without installing globally.
```bash
npx @sandbox-agent/cli server --no-token --host 0.0.0.0 --port 2468
npx @sandbox-agent/cli@0.2.x server --no-token --host 0.0.0.0 --port 2468
```
</Tab>
@ -101,7 +101,7 @@ icon: "rocket"
Run without installing globally.
```bash
bunx @sandbox-agent/cli server --no-token --host 0.0.0.0 --port 2468
bunx @sandbox-agent/cli@0.2.x server --no-token --host 0.0.0.0 --port 2468
```
</Tab>
@ -109,7 +109,7 @@ icon: "rocket"
Install globally, then run.
```bash
npm install -g @sandbox-agent/cli
npm install -g @sandbox-agent/cli@0.2.x
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
```
</Tab>
@ -118,33 +118,32 @@ icon: "rocket"
Install globally, then run.
```bash
bun add -g @sandbox-agent/cli
bun add -g @sandbox-agent/cli@0.2.x
# 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-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
```
</Tab>
<Tab title="Node.js (local)">
For local development, use `SandboxAgent.start()` to automatically spawn and manage the server as a subprocess.
For local development, use `SandboxAgent.start()` to spawn and manage the server as a subprocess.
```bash
npm install sandbox-agent
npm install sandbox-agent@0.2.x
```
```typescript
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.start();
const sdk = await SandboxAgent.start();
```
</Tab>
<Tab title="Bun (local)">
For local development, use `SandboxAgent.start()` to automatically spawn and manage the server as a subprocess.
For local development, use `SandboxAgent.start()` to spawn and manage the server as a subprocess.
```bash
bun add sandbox-agent
bun add sandbox-agent@0.2.x
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
```
@ -152,10 +151,8 @@ icon: "rocket"
```typescript
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.start();
const sdk = await SandboxAgent.start();
```
This installs the binary and starts the server for you. No manual setup required.
</Tab>
<Tab title="Build from source">
@ -167,53 +164,51 @@ icon: "rocket"
</Tab>
</Tabs>
Binding to `0.0.0.0` allows the server to accept connections from any network interface, which is required when running inside a sandbox where clients connect remotely.
Binding to `0.0.0.0` allows the server to accept connections from any network interface, which is required when running inside a sandbox where clients connect remotely.
<AccordionGroup>
<Accordion title="Configuring token">
Tokens are usually not required. Most sandbox providers (E2B, Daytona, etc.) already secure their networking at the infrastructure level, so the server endpoint is never publicly accessible. For local development, binding to `127.0.0.1` ensures only local connections are accepted.
<AccordionGroup>
<Accordion title="Configuring token">
Tokens are usually not required. Most sandbox providers (E2B, Daytona, etc.) already secure networking at the infrastructure layer.
If you need to expose the server on a public endpoint, use `--token "$SANDBOX_TOKEN"` to require authentication on all requests:
If you expose the server publicly, use `--token "$SANDBOX_TOKEN"` to require authentication:
```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 0.0.0.0 --port 2468
```
```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 0.0.0.0 --port 2468
```
Then pass the token when connecting:
Then pass the token when connecting:
<Tabs>
<Tab title="TypeScript">
```typescript
import { SandboxAgentClient } from "sandbox-agent";
<Tabs>
<Tab title="TypeScript">
```typescript
import { SandboxAgent } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://your-server:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
```
</Tab>
const sdk = await SandboxAgent.connect({
baseUrl: "http://your-server:2468",
token: process.env.SANDBOX_TOKEN,
});
```
</Tab>
<Tab title="curl">
```bash
curl "http://your-server:2468/v1/sessions" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
</Tab>
<Tab title="curl">
```bash
curl "http://your-server:2468/v1/health" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
</Tab>
<Tab title="CLI">
```bash
sandbox-agent api sessions list \
--endpoint http://your-server:2468 \
--token "$SANDBOX_TOKEN"
```
</Tab>
</Tabs>
</Accordion>
<Accordion title="CORS">
If you're calling the server from a browser, see the [CORS configuration guide](/docs/cors).
</Accordion>
</AccordionGroup>
<Tab title="CLI">
```bash
sandbox-agent --token "$SANDBOX_TOKEN" api agents list \
--endpoint http://your-server:2468
```
</Tab>
</Tabs>
</Accordion>
<Accordion title="CORS">
If you're calling the server from a browser, see the [CORS configuration guide](/cors).
</Accordion>
</AccordionGroup>
</Step>
<Step title="Install agents (optional)">
@ -226,124 +221,57 @@ icon: "rocket"
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.
If agents are not installed up front, they are lazily installed when creating a session.
</Step>
<Step title="Create a session">
<Tabs>
<Tab title="TypeScript">
```typescript
import { SandboxAgentClient } from "sandbox-agent";
```typescript
import { SandboxAgent } from "sandbox-agent";
const client = new SandboxAgentClient({
baseUrl: "http://127.0.0.1:2468",
agent: "claude",
});
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
await client.createSession("my-session", {
agent: "claude",
agentMode: "build",
permissionMode: "default",
});
```
</Tab>
const session = await sdk.createSession({
agent: "claude",
sessionInit: {
cwd: "/",
mcpServers: [],
},
});
<Tab title="curl">
```bash
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
-H "Content-Type: application/json" \
-d '{"agent":"claude","agentMode":"build","permissionMode":"default"}'
```
</Tab>
<Tab title="CLI">
```bash
sandbox-agent api sessions create my-session \
--agent claude \
--endpoint http://127.0.0.1:2468
```
</Tab>
</Tabs>
console.log(session.id);
```
</Step>
<Step title="Send a message">
<Tabs>
<Tab title="TypeScript">
```typescript
await client.postMessage("my-session", {
message: "Summarize the repository and suggest next steps.",
});
```
</Tab>
```typescript
const result = await session.prompt([
{ type: "text", text: "Summarize the repository and suggest next steps." },
]);
<Tab title="curl">
```bash
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
-H "Content-Type: application/json" \
-d '{"message":"Summarize the repository and suggest next steps."}'
```
</Tab>
<Tab title="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
```
</Tab>
</Tabs>
console.log(result.stopReason);
```
</Step>
<Step title="Read events">
<Tabs>
<Tab title="TypeScript">
```typescript
// Poll for events
const events = await client.getEvents("my-session", { offset: 0, limit: 50 });
```typescript
const off = session.onEvent((event) => {
console.log(event.sender, event.payload);
});
// Or stream events
for await (const event of client.streamEvents("my-session", { offset: 0 })) {
console.log(event.type, event.data);
}
```
</Tab>
const page = await sdk.getEvents({
sessionId: session.id,
limit: 50,
});
<Tab title="curl">
```bash
# Poll for events
curl "http://127.0.0.1:2468/v1/sessions/my-session/events?offset=0&limit=50"
# Stream events via SSE
curl "http://127.0.0.1:2468/v1/sessions/my-session/events/sse?offset=0"
# 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 "Content-Type: application/json" \
-d '{"message":"Hello"}'
```
</Tab>
<Tab title="CLI">
```bash
# Poll for events
sandbox-agent api sessions events my-session \
--endpoint http://127.0.0.1:2468
# Stream events via SSE
sandbox-agent api sessions events-sse my-session \
--endpoint http://127.0.0.1:2468
# Single-turn stream
sandbox-agent api sessions send-message-stream my-session \
--message "Hello" \
--endpoint http://127.0.0.1:2468
```
</Tab>
</Tabs>
console.log(page.items.length);
off();
```
</Step>
<Step title="Test with Inspector">
Open the Inspector UI at `/ui/` on your server (e.g., `http://localhost:2468/ui/`) to inspect session state using a GUI.
Open the Inspector UI at `/ui/` on your server (for example, `http://localhost:2468/ui/`) to inspect sessions and events in a GUI.
<Frame>
<img src="/images/inspector.png" alt="Sandbox Agent Inspector" />
@ -354,13 +282,13 @@ icon: "rocket"
## Next steps
<CardGroup cols={3}>
<Card title="Build a Chat UI" icon="comments" href="/building-chat-ui">
Learn how to build a chat interface for your agent.
<Card title="Session Persistence" icon="database" href="/session-persistence">
Configure in-memory, Rivet Actor state, IndexedDB, SQLite, and Postgres persistence.
</Card>
<Card title="Manage Sessions" icon="database" href="/manage-sessions">
Persist and replay agent transcripts.
<Card title="Deploy to a Sandbox" icon="box" href="/deploy/local">
Deploy your agent to E2B, Daytona, Docker, Vercel, or Cloudflare.
</Card>
<Card title="Deploy to a Sandbox" icon="box" href="/deploy">
Deploy your agent to E2B, Daytona, or Vercel Sandboxes.
<Card title="SDK Overview" icon="compass" href="/sdk-overview">
Use the latest TypeScript SDK API.
</Card>
</CardGroup>

174
docs/sdk-overview.mdx Normal file
View file

@ -0,0 +1,174 @@
---
title: "SDK Overview"
description: "Use the TypeScript SDK to manage Sandbox Agent sessions and APIs."
icon: "compass"
---
The TypeScript SDK is centered on `sandbox-agent` and its `SandboxAgent` class.
## Install
<Tabs>
<Tab title="npm">
```bash
npm install sandbox-agent@0.2.x
```
</Tab>
<Tab title="bun">
```bash
bun add sandbox-agent@0.2.x
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
```
</Tab>
</Tabs>
## Optional persistence drivers
```bash
npm install @sandbox-agent/persist-indexeddb@0.2.x @sandbox-agent/persist-sqlite@0.2.x @sandbox-agent/persist-postgres@0.2.x
```
## Create a client
```ts
import { SandboxAgent } from "sandbox-agent";
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
```
With persistence:
```ts
import { SandboxAgent } from "sandbox-agent";
import { SQLiteSessionPersistDriver } from "@sandbox-agent/persist-sqlite";
const persist = new SQLiteSessionPersistDriver({
filename: "./sessions.db",
});
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
persist,
});
```
Local autospawn (Node.js only):
```ts
import { SandboxAgent } from "sandbox-agent";
const localSdk = await SandboxAgent.start();
await localSdk.dispose();
```
## Session flow
```ts
const session = await sdk.createSession({
agent: "mock",
sessionInit: {
cwd: "/",
mcpServers: [],
},
});
const prompt = await session.prompt([
{ type: "text", text: "Summarize this repository." },
]);
console.log(prompt.stopReason);
```
Load and destroy:
```ts
const restored = await sdk.resumeSession(session.id);
await restored.prompt([{ type: "text", text: "Continue from previous context." }]);
await sdk.destroySession(restored.id);
```
## Events
Subscribe to live events:
```ts
const unsubscribe = session.onEvent((event) => {
console.log(event.eventIndex, event.sender, event.payload);
});
await session.prompt([{ type: "text", text: "Give me a short summary." }]);
unsubscribe();
```
Fetch persisted events:
```ts
const page = await sdk.getEvents({
sessionId: session.id,
limit: 100,
});
console.log(page.items.length);
```
## Control-plane and HTTP helpers
```ts
const health = await sdk.getHealth();
const agents = await sdk.listAgents();
await sdk.installAgent("codex", { reinstall: true });
const entries = await sdk.listFsEntries({ path: "." });
const writeResult = await sdk.writeFsFile({ path: "./hello.txt" }, "hello");
console.log(health.status, agents.agents.length, entries.length, writeResult.path);
```
## Error handling
```ts
import { SandboxAgentError } from "sandbox-agent";
try {
await sdk.listAgents();
} catch (error) {
if (error instanceof SandboxAgentError) {
console.error(error.status, error.problem);
}
}
```
## Inspector URL
```ts
import { buildInspectorUrl } from "sandbox-agent";
const url = buildInspectorUrl({
baseUrl: "https://your-sandbox-agent.example.com",
headers: { "X-Custom-Header": "value" },
});
console.log(url);
```
Parameters:
- `baseUrl` (required): Sandbox Agent server URL
- `token` (optional): Bearer token for authenticated servers
- `headers` (optional): Additional request headers
## Types
```ts
import type {
AgentInfo,
HealthResponse,
SessionEvent,
SessionRecord,
} from "sandbox-agent";
```

191
docs/security.mdx Normal file
View file

@ -0,0 +1,191 @@
---
title: "Security"
description: "Backend-first auth and access control patterns."
icon: "shield"
---
As covered in [Architecture](/architecture), run the Sandbox Agent client on your backend, not in the browser.
This keeps sandbox credentials private and gives you one place for authz, rate limiting, and audit logging.
## Auth model
Implement auth however it fits your stack (sessions, JWT, API keys, etc.), but enforce it before any sandbox-bound request.
Minimum checks:
- Authenticate the caller.
- Authorize access to the target workspace/sandbox/session.
- Apply request rate limits and request logging.
## Examples
### Rivet
<CodeGroup>
```ts Actor (server)
import { UserError, actor } from "rivetkit";
import { SandboxAgent } from "sandbox-agent";
type ConnParams = {
accessToken: string;
};
type WorkspaceClaims = {
sub: string;
workspaceId: string;
role: "owner" | "member" | "viewer";
};
async function verifyWorkspaceToken(
token: string,
workspaceId: string,
): Promise<WorkspaceClaims | null> {
// Validate JWT/session token here, then enforce workspace scope.
// Return null when invalid/expired/not a member.
if (!token) return null;
return { sub: "user_123", workspaceId, role: "member" };
}
export const workspace = actor({
state: {
events: [] as Array<{ userId: string; prompt: string; createdAt: number }>,
},
onBeforeConnect: async (c, params: ConnParams) => {
const claims = await verifyWorkspaceToken(params.accessToken, c.key[0]);
if (!claims) {
throw new UserError("Forbidden", { code: "forbidden" });
}
},
createConnState: async (c, params: ConnParams) => {
const claims = await verifyWorkspaceToken(params.accessToken, c.key[0]);
if (!claims) {
throw new UserError("Forbidden", { code: "forbidden" });
}
return {
userId: claims.sub,
role: claims.role,
workspaceId: claims.workspaceId,
};
},
actions: {
submitPrompt: async (c, prompt: string) => {
if (!c.conn) {
throw new UserError("Connection required", { code: "connection_required" });
}
if (c.conn.state.role === "viewer") {
throw new UserError("Insufficient permissions", { code: "forbidden" });
}
// Connect to Sandbox Agent from the actor (server-side only).
// Sandbox credentials never reach the client.
const sdk = await SandboxAgent.connect({
baseUrl: process.env.SANDBOX_URL!,
token: process.env.SANDBOX_TOKEN,
});
const session = await sdk.createSession({
agent: "claude",
sessionInit: { cwd: "/workspace" },
});
session.onEvent((event) => {
c.broadcast("session.event", {
userId: c.conn!.state.userId,
eventIndex: event.eventIndex,
sender: event.sender,
payload: event.payload,
});
});
const result = await session.prompt([
{ type: "text", text: prompt },
]);
c.state.events.push({
userId: c.conn.state.userId,
prompt,
createdAt: Date.now(),
});
return { stopReason: result.stopReason };
},
},
});
```
```ts Client (browser)
import { createClient } from "rivetkit/client";
import type { registry } from "./actors";
const client = createClient<typeof registry>({
endpoint: process.env.NEXT_PUBLIC_RIVET_ENDPOINT!,
});
const handle = client.workspace.getOrCreate(["ws_123"], {
params: { accessToken: userJwt },
});
const conn = handle.connect();
conn.on("session.event", (event) => {
console.log(event.sender, event.payload);
});
const result = await conn.submitPrompt("Plan a refactor for auth middleware.");
console.log(result.stopReason);
```
</CodeGroup>
Use [onBeforeConnect](https://rivet.dev/docs/actors/authentication), [connection params](https://rivet.dev/docs/actors/connections), and [actor keys](https://rivet.dev/docs/actors/keys) together so each actor enforces auth per workspace.
### Hono
```ts
import { Hono } from "hono";
import { bearerAuth } from "hono/bearer-auth";
const app = new Hono();
app.use("/sandbox/*", bearerAuth({ token: process.env.APP_API_TOKEN! }));
app.all("/sandbox/*", async (c) => {
const incoming = new URL(c.req.url);
const upstreamUrl = new URL(process.env.SANDBOX_URL!);
upstreamUrl.pathname = incoming.pathname.replace(/^\/sandbox/, "/v1");
upstreamUrl.search = incoming.search;
const headers = new Headers();
headers.set("authorization", `Bearer ${process.env.SANDBOX_TOKEN ?? ""}`);
const accept = c.req.header("accept");
if (accept) headers.set("accept", accept);
const contentType = c.req.header("content-type");
if (contentType) headers.set("content-type", contentType);
const body =
c.req.method === "POST" || c.req.method === "PUT" || c.req.method === "PATCH"
? await c.req.text()
: undefined;
const upstream = await fetch(upstreamUrl, {
method: c.req.method,
headers,
body,
});
return new Response(upstream.body, {
status: upstream.status,
headers: upstream.headers,
});
});
```

183
docs/session-persistence.mdx Normal file
View file

@ -0,0 +1,183 @@
---
title: "Persisting Sessions"
description: "Choose and configure session persistence for the TypeScript SDK."
icon: "database"
---
The TypeScript SDK uses a `SessionPersistDriver` to store session records and event history.
If you do not provide one, the SDK uses in-memory storage.
With persistence enabled, sessions can be restored after runtime/session loss. See [Session Restoration](/session-restoration).
Each driver stores:
- `SessionRecord` (`id`, `agent`, `agentSessionId`, `lastConnectionId`, `createdAt`, optional `destroyedAt`, optional `sessionInit`)
- `SessionEvent` (`id`, `eventIndex`, `sessionId`, `connectionId`, `sender`, `payload`, `createdAt`)
## Persistence drivers
### In-memory
Best for local dev and ephemeral workloads.
```ts
import { InMemorySessionPersistDriver, SandboxAgent } from "sandbox-agent";
const persist = new InMemorySessionPersistDriver({
maxSessions: 1024,
maxEventsPerSession: 500,
});
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
persist,
});
```
### Rivet
Recommended for sandbox orchestration with actor state.
```bash
npm install @sandbox-agent/persist-rivet@0.1.x
```
```ts
import { actor } from "rivetkit";
import { SandboxAgent } from "sandbox-agent";
import { RivetSessionPersistDriver, type RivetPersistState } from "@sandbox-agent/persist-rivet";
type PersistedState = RivetPersistState & {
sandboxId: string;
baseUrl: string;
};
export default actor({
createState: async () => {
return {
sandboxId: "sbx_123",
baseUrl: "http://127.0.0.1:2468",
} satisfies Partial<PersistedState>;
},
createVars: async (c) => {
const persist = new RivetSessionPersistDriver(c);
const sdk = await SandboxAgent.connect({
baseUrl: c.state.baseUrl,
persist,
});
const session = await sdk.resumeOrCreateSession({ id: "default", agent: "codex" });
const unsubscribe = session.onEvent((event) => {
c.broadcast("session.event", event);
});
return { sdk, session, unsubscribe };
},
actions: {
sendMessage: async (c, message: string) => {
await c.vars.session.prompt([{ type: "text", text: message }]);
},
},
onSleep: async (c) => {
c.vars.unsubscribe?.();
await c.vars.sdk.dispose();
},
});
```
### IndexedDB
Best for browser apps that should survive reloads.
```bash
npm install @sandbox-agent/persist-indexeddb@0.2.x
```
```ts
import { SandboxAgent } from "sandbox-agent";
import { IndexedDbSessionPersistDriver } from "@sandbox-agent/persist-indexeddb";
const persist = new IndexedDbSessionPersistDriver({
databaseName: "sandbox-agent-session-store",
});
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
persist,
});
```
### SQLite
Best for local/server Node apps that need durable storage without a DB server.
```bash
npm install @sandbox-agent/persist-sqlite@0.2.x
```
```ts
import { SandboxAgent } from "sandbox-agent";
import { SQLiteSessionPersistDriver } from "@sandbox-agent/persist-sqlite";
const persist = new SQLiteSessionPersistDriver({
filename: "./sandbox-agent.db",
});
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
persist,
});
```
### Postgres
Use when you already run Postgres and want shared relational storage.
```bash
npm install @sandbox-agent/persist-postgres@0.2.x
```
```ts
import { SandboxAgent } from "sandbox-agent";
import { PostgresSessionPersistDriver } from "@sandbox-agent/persist-postgres";
const persist = new PostgresSessionPersistDriver({
connectionString: process.env.DATABASE_URL,
schema: "public",
});
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
persist,
});
```
### Custom driver
Implement `SessionPersistDriver` for custom backends.
```ts
import type { SessionPersistDriver } from "sandbox-agent";
class MyDriver implements SessionPersistDriver {
async getSession(id) { return null; }
async listSessions(request) { return { items: [] }; }
async updateSession(session) {}
async listEvents(request) { return { items: [] }; }
async insertEvent(event) {}
}
```
## Replay controls
`SandboxAgent.connect(...)` supports:
- `replayMaxEvents` (default `50`)
- `replayMaxChars` (default `12000`)
These cap replay size when restoring sessions.
## Related docs
- [SDK Overview](/sdk-overview)
- [Session Restoration](/session-restoration)

33
docs/session-restoration.mdx Normal file
View file

@ -0,0 +1,33 @@
---
title: "Session Restoration"
description: "How the TypeScript SDK restores sessions after connection/runtime loss."
---
Sandbox Agent automatically restores stale sessions when live session state is no longer available.
This is driven by the configured `SessionPersistDriver` (`inMemory`, IndexedDB, SQLite, Postgres, or custom).
## How Auto-Restore Works
When you call `session.prompt(...)` (or `resumeSession(...)`) and the saved session points to a stale connection, the SDK:
1. Recreates a fresh session for the same local session id.
2. Rebinds the local session to the new runtime session id.
3. Replays recent persisted events into the next prompt as context.
This happens automatically; you do not need to manually rebuild the session.
## Replay Limits
Replay payload size is capped by:
- `replayMaxEvents` (default `50`)
- `replayMaxChars` (default `12000`)
These controls limit prompt growth during restore while preserving recent context.
## Related Docs
- [SDK Overview](/sdk-overview)
- [Persisting Sessions](/session-persistence)
- [Agent Sessions](/agent-sessions)

109
docs/skills-config.mdx
View file

@ -1,88 +1,81 @@
---
title: "Skills"
description: "Auto-load skills into agent sessions."
description: "Configure skill sources for agent sessions."
sidebarTitle: "Skills"
icon: "sparkles"
---
Skills are local instruction bundles stored in `SKILL.md` files. Sandbox Agent can fetch, discover, and link skill directories into agent-specific skill paths at session start using the `skills.sources` field. The format is fully compatible with [skills.sh](https://skills.sh).
Skills are local instruction bundles stored in `SKILL.md` files.
## Session Config
## Configuring skills
Pass `skills.sources` when creating a session to load skills from GitHub repos, local paths, or git URLs.
Use `setSkillsConfig` / `getSkillsConfig` / `deleteSkillsConfig` to manage skill source config by directory + skill name.
<CodeGroup>
```ts
import { SandboxAgent } from "sandbox-agent";
```ts TypeScript
import { SandboxAgentClient } from "sandbox-agent";
const client = new SandboxAgentClient({
const sdk = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
agent: "mock",
});
});
await client.createSession("claude-skills", {
agent: "claude",
skills: {
// Add a skill
await sdk.setSkillsConfig(
{
directory: "/workspace",
skillName: "default",
},
{
sources: [
{ type: "github", source: "rivet-dev/skills", skills: ["sandbox-agent"] },
{ type: "local", source: "/workspace/my-custom-skill" },
],
},
);
// Create a session using the configured skills
const session = await sdk.createSession({
agent: "claude",
sessionInit: {
cwd: "/workspace",
},
});
await session.prompt([
{ type: "text", text: "Use available skills to help with this task." },
]);
// List skills
const config = await sdk.getSkillsConfig({
directory: "/workspace",
skillName: "default",
});
console.log(config.sources.length);
// Delete skill
await sdk.deleteSkillsConfig({
directory: "/workspace",
skillName: "default",
});
```
```bash cURL
curl -X POST "http://127.0.0.1:2468/v1/sessions/claude-skills" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "claude",
"skills": {
"sources": [
{ "type": "github", "source": "rivet-dev/skills", "skills": ["sandbox-agent"] },
{ "type": "local", "source": "/workspace/my-custom-skill" }
]
}
}'
```
## Skill sources
</CodeGroup>
Each skill directory must contain `SKILL.md`. See [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for tips on writing effective skills.
## Skill Sources
Each entry in `skills.sources` describes where to find skills. Three source types are supported:
Each `skills.sources` entry describes where to find skills.
| Type | `source` value | Example |
|------|---------------|---------|
| `github` | `owner/repo` | `"rivet-dev/skills"` |
| `local` | Filesystem path | `"/workspace/my-skill"` |
| `git` | Git clone URL | `"https://git.example.com/skills.git"` |
| `local` | filesystem path | `"/workspace/my-skill"` |
| `git` | git clone URL | `"https://git.example.com/skills.git"` |
### Optional fields
Optional fields:
- **`skills`** — Array of skill directory names to include. When omitted, all discovered skills are installed.
- **`ref`** — Branch, tag, or commit to check out (default: HEAD). Applies to `github` and `git` types.
- **`subpath`** — Subdirectory within the repo to search for skills.
- `skills`: subset of skill directory names to include
- `ref`: branch/tag/commit (for `github` and `git`)
- `subpath`: subdirectory within repo to scan
## Custom Skills
## Custom skills
To write, upload, and configure your own skills inside the sandbox, see [Custom Tools](/custom-tools).
## Advanced
### Discovery logic
After resolving a source to a local directory (cloning if needed), Sandbox Agent discovers skills by:
1. Checking if the directory itself contains `SKILL.md`.
2. Scanning `skills/` subdirectory for child directories containing `SKILL.md`.
3. Scanning immediate children of the directory for `SKILL.md`.
Discovered skills are symlinked into project-local skill roots (`.claude/skills/<name>`, `.agents/skills/<name>`, `.opencode/skill/<name>`).
### Caching
GitHub sources are downloaded as zip archives and git sources are cloned to `~/.sandbox-agent/skills-cache/` and updated on subsequent session creations. GitHub sources do not require `git` to be installed.