sandbox-agent

# 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](https://rivet.dev/discord) or file an issue on [GitHub](https://github.com/rivet-dev/sandbox-agent/issues) 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 skill (optional) #### npx ```bash npx skills add rivet-dev/skills -s sandbox-agent ``` #### bunx ```bash bunx skills add rivet-dev/skills -s sandbox-agent ``` ### Set environment variables Each coding agent requires API keys to connect to their respective LLM providers. #### Local shell ```bash export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-..." ``` #### E2B ```typescript import { Sandbox } from "@e2b/code-interpreter"; const envs: Record<string, string> = {}; if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY; if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY; const sandbox = await Sandbox.create({ envs }); ``` #### Daytona ```typescript import { Daytona } from "@daytonaio/sdk"; const envVars: Record<string, string> = {}; if (process.env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY; if (process.env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = process.env.OPENAI_API_KEY; const daytona = new Daytona(); const sandbox = await daytona.create({ snapshot: "sandbox-agent-ready", envVars, }); ``` #### Docker ```bash docker run -p 2468:2468 \ -e ANTHROPIC_API_KEY="sk-ant-..." \ -e OPENAI_API_KEY="sk-..." \ rivetdev/sandbox-agent:0.5.4-full \ server --no-token --host 0.0.0.0 --port 2468 ``` #### 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. #### Testing without API keys Use the `mock` agent for SDK and integration testing without provider credentials. #### Multi-tenant and per-user billing For per-tenant token tracking, budget enforcement, or usage-based billing, see [LLM Credentials](/sandbox-agent/docs/llm-credentials) for gateway options like OpenRouter, LiteLLM, and Portkey. ### Run the server #### curl Install and run the binary directly. ```bash curl -fsSL https://releases.rivet.dev/sandbox-agent/0.5.x/install.sh | sh sandbox-agent server --no-token --host 0.0.0.0 --port 2468 ``` #### npx Run without installing globally. ```bash npx @sandbox-agent/cli@0.5.x server --no-token --host 0.0.0.0 --port 2468 ``` #### bunx Run without installing globally. ```bash bunx @sandbox-agent/cli@0.5.x server --no-token --host 0.0.0.0 --port 2468 ``` #### npm i -g Install globally, then run. ```bash npm install -g @sandbox-agent/cli@0.5.x sandbox-agent server --no-token --host 0.0.0.0 --port 2468 ``` #### bun add -g Install globally, then run. ```bash bun add -g @sandbox-agent/cli@0.5.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-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64 sandbox-agent server --no-token --host 0.0.0.0 --port 2468 ``` #### Node.js (local) For local development, use `SandboxAgent.start()` to spawn and manage the server as a subprocess. ```bash npm install sandbox-agent@0.5.x ``` ```typescript import { SandboxAgent } from "sandbox-agent"; const sdk = await SandboxAgent.start(); ``` #### Bun (local) For local development, use `SandboxAgent.start()` to spawn and manage the server as a subprocess. ```bash bun add sandbox-agent@0.5.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 ``` ```typescript import { SandboxAgent } from "sandbox-agent"; const sdk = await SandboxAgent.start(); ``` #### Build from source If you're running from source instead of the installed CLI. ```bash cargo run -p sandbox-agent -- server --no-token --host 0.0.0.0 --port 2468 ``` 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. #### Configuring token Tokens are usually not required. Most sandbox providers (E2B, Daytona, etc.) already secure networking at the infrastructure layer. 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 ``` Then pass the token when connecting: #### TypeScript ```typescript import { SandboxAgent } from "sandbox-agent"; const sdk = await SandboxAgent.connect({ baseUrl: "http://your-server:2468", token: process.env.SANDBOX_TOKEN, }); ``` #### curl ```bash curl "http://your-server:2468/v1/health" \ -H "Authorization: Bearer $SANDBOX_TOKEN" ``` #### CLI ```bash sandbox-agent --token "$SANDBOX_TOKEN" api agents list \ --endpoint http://your-server:2468 ``` #### CORS If you're calling the server from a browser, see the [CORS configuration guide](/sandbox-agent/docs/cors). ### Install agents (optional) To preinstall agents: ```bash sandbox-agent install-agent --all ``` If agents are not installed up front, they are lazily installed when creating a session. ### Install desktop dependencies (optional, Linux only) If you want to use `/v1/desktop/*`, install the desktop runtime packages first: ```bash sandbox-agent install desktop --yes ``` Then use `GET /v1/desktop/status` or `sdk.getDesktopStatus()` to verify the runtime is ready before calling desktop screenshot or input APIs. ### Create a session ```typescript import { SandboxAgent } from "sandbox-agent"; const sdk = await SandboxAgent.connect({ baseUrl: "http://127.0.0.1:2468", }); const session = await sdk.createSession({ agent: "claude", sessionInit: { cwd: "/", mcpServers: [], }, }); console.log(session.id); ``` ### Send a message ```typescript const result = await session.prompt([ { type: "text", text: "Summarize the repository and suggest next steps." }, ]); console.log(result.stopReason); ``` ### Read events ```typescript const off = session.onEvent((event) => { console.log(event.sender, event.payload); }); const page = await sdk.getEvents({ sessionId: session.id, limit: 50, }); console.log(page.items.length); off(); ``` ### Test with Inspector Open the Inspector UI at `/ui/` on your server (for example, `http://localhost:2468/ui/`) to inspect sessions and events in a GUI.  ## Next steps - [Session Persistence](/sandbox-agent/docs/session-persistence) — Configure in-memory, Rivet Actor state, IndexedDB, SQLite, and Postgres persistence. - [Deploy to a Sandbox](/sandbox-agent/docs/deploy/local) — Deploy your agent to E2B, Daytona, Docker, Vercel, or Cloudflare. - [SDK Overview](/sandbox-agent/docs/sdk-overview) — Use the latest TypeScript SDK API. ## Reference Map ### Agents - [Amp](references/agents/amp.md) - [Claude](references/agents/claude.md) - [Codex](references/agents/codex.md) - [Cursor](references/agents/cursor.md) - [OpenCode](references/agents/opencode.md) - [Pi](references/agents/pi.md) ### AI - [llms.txt](references/ai/llms-txt.md) - [skill.md](references/ai/skill.md) ### Api Reference - [AcpEnvelope](references/api-reference/schemas/acpenvelope.md) - [AcpPostQuery](references/api-reference/schemas/acppostquery.md) - [AcpServerInfo](references/api-reference/schemas/acpserverinfo.md) - [AcpServerListResponse](references/api-reference/schemas/acpserverlistresponse.md) - [AgentCapabilities](references/api-reference/schemas/agentcapabilities.md) - [AgentInfo](references/api-reference/schemas/agentinfo.md) - [AgentInstallArtifact](references/api-reference/schemas/agentinstallartifact.md) - [AgentInstallRequest](references/api-reference/schemas/agentinstallrequest.md) - [AgentInstallResponse](references/api-reference/schemas/agentinstallresponse.md) - [AgentListResponse](references/api-reference/schemas/agentlistresponse.md) - [Authentication](references/api-reference/authentication.md) - [Capture a desktop screenshot region.](references/api-reference/operations/get_v1_desktop_screenshot_region.md) - [Capture a full desktop screenshot.](references/api-reference/operations/get_v1_desktop_screenshot.md) - [Click on the desktop.](references/api-reference/operations/post_v1_desktop_mouse_click.md) - [Create a long-lived managed process.](references/api-reference/operations/post_v1_processes.md) - [Delete a desktop recording.](references/api-reference/operations/delete_v1_desktop_recording.md) - [Delete a process record.](references/api-reference/operations/delete_v1_process.md) - [delete_v1_acp](references/api-reference/operations/delete_v1_acp.md) - [delete_v1_config_mcp](references/api-reference/operations/delete_v1_config_mcp.md) - [delete_v1_config_skills](references/api-reference/operations/delete_v1_config_skills.md) - [delete_v1_fs_entry](references/api-reference/operations/delete_v1_fs_entry.md) - [DesktopActionResponse](references/api-reference/schemas/desktopactionresponse.md) - [DesktopClipboardQuery](references/api-reference/schemas/desktopclipboardquery.md) - [DesktopClipboardResponse](references/api-reference/schemas/desktopclipboardresponse.md) - [DesktopClipboardWriteRequest](references/api-reference/schemas/desktopclipboardwriterequest.md) - [DesktopDisplayInfoResponse](references/api-reference/schemas/desktopdisplayinforesponse.md) - [DesktopErrorInfo](references/api-reference/schemas/desktoperrorinfo.md) - [DesktopKeyboardDownRequest](references/api-reference/schemas/desktopkeyboarddownrequest.md) - [DesktopKeyboardPressRequest](references/api-reference/schemas/desktopkeyboardpressrequest.md) - [DesktopKeyboardTypeRequest](references/api-reference/schemas/desktopkeyboardtyperequest.md) - [DesktopKeyboardUpRequest](references/api-reference/schemas/desktopkeyboarduprequest.md) - [DesktopKeyModifiers](references/api-reference/schemas/desktopkeymodifiers.md) - [DesktopLaunchRequest](references/api-reference/schemas/desktoplaunchrequest.md) - [DesktopLaunchResponse](references/api-reference/schemas/desktoplaunchresponse.md) - [DesktopMouseButton](references/api-reference/schemas/desktopmousebutton.md) - [DesktopMouseClickRequest](references/api-reference/schemas/desktopmouseclickrequest.md) - [DesktopMouseDownRequest](references/api-reference/schemas/desktopmousedownrequest.md) - [DesktopMouseDragRequest](references/api-reference/schemas/desktopmousedragrequest.md) - [DesktopMouseMoveRequest](references/api-reference/schemas/desktopmousemoverequest.md)