Sandbox Agent

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

What To Do If You Get Stuck

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

Provide the user with a pre-generated report with:

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

Quickstart

Install

npm

npm install sandbox-agent@0.3.x

bun

bun add sandbox-agent@0.3.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-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64

Start the sandbox

SandboxAgent.start() provisions a sandbox, starts a lightweight Sandbox Agent server inside it, and connects your SDK client.

Local

npm install sandbox-agent@0.3.x

import { SandboxAgent } from "sandbox-agent";
import { local } from "sandbox-agent/local";

// Runs on your machine. Inherits process.env automatically.
const client = await SandboxAgent.start({
  sandbox: local(),
});

See Local deploy guide

E2B

npm install sandbox-agent@0.3.x @e2b/code-interpreter

import { SandboxAgent } from "sandbox-agent";
import { e2b } from "sandbox-agent/e2b";

// Provisions a cloud sandbox on E2B, installs the server, and connects.
const client = await SandboxAgent.start({
  sandbox: e2b(),
});

See E2B deploy guide

Daytona

npm install sandbox-agent@0.3.x @daytonaio/sdk

import { SandboxAgent } from "sandbox-agent";
import { daytona } from "sandbox-agent/daytona";

// Provisions a Daytona workspace with the server pre-installed.
const client = await SandboxAgent.start({
  sandbox: daytona(),
});

See Daytona deploy guide

Vercel

npm install sandbox-agent@0.3.x @vercel/sandbox

import { SandboxAgent } from "sandbox-agent";
import { vercel } from "sandbox-agent/vercel";

// Provisions a Vercel sandbox with the server installed on boot.
const client = await SandboxAgent.start({
  sandbox: vercel(),
});

See Vercel deploy guide

Modal

npm install sandbox-agent@0.3.x modal

import { SandboxAgent } from "sandbox-agent";
import { modal } from "sandbox-agent/modal";

// Builds a container image with agents pre-installed (cached after first run),
// starts a Modal sandbox from that image, and connects.
const client = await SandboxAgent.start({
  sandbox: modal(),
});

See Modal deploy guide

Cloudflare

npm install sandbox-agent@0.3.x @cloudflare/sandbox

import { SandboxAgent } from "sandbox-agent";
import { cloudflare } from "sandbox-agent/cloudflare";
import { SandboxClient } from "@cloudflare/sandbox";

// Uses the Cloudflare Sandbox SDK to provision and connect.
// The Cloudflare SDK handles server lifecycle internally.
const cfSandboxClient = new SandboxClient();
const client = await SandboxAgent.start({
  sandbox: cloudflare({ sdk: cfSandboxClient }),
});

See Cloudflare deploy guide

Docker

npm install sandbox-agent@0.3.x dockerode get-port

import { SandboxAgent } from "sandbox-agent";
import { docker } from "sandbox-agent/docker";

// Runs a Docker container locally. Good for testing.
const client = await SandboxAgent.start({
  sandbox: docker(),
});

See Docker deploy guide

More info:

Passing LLM credentials

Agents need API keys for their LLM provider. Each provider passes credentials differently:

// Local — inherits process.env automatically

// E2B
e2b({ create: { envs: { ANTHROPIC_API_KEY: "..." } } })

// Daytona
daytona({ create: { envVars: { ANTHROPIC_API_KEY: "..." } } })

// Vercel
vercel({ create: { env: { ANTHROPIC_API_KEY: "..." } } })

// Modal
modal({ create: { secrets: { ANTHROPIC_API_KEY: "..." } } })

// Docker
docker({ env: ["ANTHROPIC_API_KEY=..."] })

For multi-tenant billing, per-user keys, and gateway options, see LLM Credentials.

Implementing a custom provider

Implement the SandboxProvider interface to use any sandbox platform:

import { SandboxAgent, type SandboxProvider } from "sandbox-agent";

const myProvider: SandboxProvider = {
  name: "my-provider",
  async create() {
    // Provision a sandbox, install & start the server, return an ID
    return "sandbox-123";
  },
  async destroy(sandboxId) {
    // Tear down the sandbox
  },
  async getUrl(sandboxId) {
    // Return the Sandbox Agent server URL
    return `https://${sandboxId}.my-platform.dev:3000`;
  },
};

const client = await SandboxAgent.start({
  sandbox: myProvider,
});

Connecting to an existing server

If you already have a Sandbox Agent server running, connect directly:

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

Starting the server manually

curl

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

npx

npx @sandbox-agent/cli@0.3.x server --no-token --host 0.0.0.0 --port 2468

Docker

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

Create a session and send a prompt

const session = await client.createSession({
  agent: "claude",
});

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

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

console.log(result.stopReason);

const session = await client.createSession({
  agent: "codex",
});

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

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

console.log(result.stopReason);

const session = await client.createSession({
  agent: "opencode",
});

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

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

console.log(result.stopReason);

const session = await client.createSession({
  agent: "cursor",
});

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

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

console.log(result.stopReason);

const session = await client.createSession({
  agent: "amp",
});

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

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

console.log(result.stopReason);

const session = await client.createSession({
  agent: "pi",
});

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

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

console.log(result.stopReason);

See Agent Sessions for the full sessions API.

Clean up

await client.destroySandbox(); // tears down the sandbox and disconnects

Use client.dispose() instead to disconnect without destroying the sandbox (for reconnecting later).

Inspect with the UI

Open the Inspector at /ui/ on your server (e.g. http://localhost:2468/ui/) to view sessions and events in a GUI.

Full example

import { SandboxAgent } from "sandbox-agent";
import { e2b } from "sandbox-agent/e2b";

const client = await SandboxAgent.start({
  sandbox: e2b({
    create: {
      envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
    },
  }),
});

try {
  const session = await client.createSession({ agent: "claude" });

  session.onEvent((event) => {
    console.log(`[${event.sender}]`, JSON.stringify(event.payload));
  });

  const result = await session.prompt([
    { type: "text", text: "Write a function that checks if a number is prime." },
  ]);

  console.log("Done:", result.stopReason);
} finally {
  await client.destroySandbox();
}

Next steps

• SDK Overview — Full TypeScript SDK API surface.

• Deploy to a Sandbox — Deploy to E2B, Daytona, Docker, Vercel, or Cloudflare.

Reference Map

Agents

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

AI

• llms.txt
• skill.md

Deploy

• BoxLite
• Cloudflare
• ComputeSDK
• Daytona
• Docker
• E2B
• Foundry Self-Hosting
• Local
• Modal
• Vercel

General

• Agent Sessions
• Architecture
• Attachments
• CLI Reference
• CORS Configuration
• Custom Tools
• Daemon
• File System
• Gigacode
• Inspector
• LLM Credentials
• Manage Sessions
• MCP
• Multiplayer
• Observability
• OpenCode Compatibility
• Orchestration Architecture
• Persisting Sessions
• Pi Support Plan
• Processes
• Quickstart
• React Components
• SDK Overview
• Security
• Session Restoration
• Session Transcript Schema
• Skills
• Telemetry
• Troubleshooting