Quickstart

Start the server and send your first message.

1. Install skill (optional)

   npx

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

   bunx

   bunx skills add rivet-dev/skills -s sandbox-agent
   
2. Set environment variables

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

   Local shell

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

   E2B

   import { Sandbox } from "@e2b/code-interpreter";
   
   const envs: Record<string, string> = {};
   if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
   if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
   
   const sandbox = await Sandbox.create({ envs });
   

   Daytona

   import { Daytona } from "@daytonaio/sdk";
   
   const envVars: Record<string, string> = {};
   if (process.env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
   if (process.env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
   
   const daytona = new Daytona();
   const sandbox = await daytona.create({
     snapshot: "sandbox-agent-ready",
     envVars,
   });
   

   Docker

   docker run -p 2468:2468 \
     -e ANTHROPIC_API_KEY="sk-ant-..." \
     -e OPENAI_API_KEY="sk-..." \
     rivetdev/sandbox-agent:0.4.2-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 for gateway options like OpenRouter, LiteLLM, and Portkey.

3. Run the server

   curl

   Install and run the binary directly.

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

   npx

   Run without installing globally.

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

   bunx

   Run without installing globally.

   bunx @sandbox-agent/cli@0.4.x server --no-token --host 0.0.0.0 --port 2468
   

   npm i -g

   Install globally, then run.

   npm install -g @sandbox-agent/cli@0.4.x
   sandbox-agent server --no-token --host 0.0.0.0 --port 2468
   

   bun add -g

   Install globally, then run.

   bun add -g @sandbox-agent/cli@0.4.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.

   npm install sandbox-agent@0.4.x
   

   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.

   bun add sandbox-agent@0.4.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
   

   import { SandboxAgent } from "sandbox-agent";
   
   const sdk = await SandboxAgent.start();
   

   Build from source

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

   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:

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

   Then pass the token when connecting:

   TypeScript

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

   curl

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

   CLI

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

   CORS

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

4. Install agents (optional)

   To preinstall agents:

   sandbox-agent install-agent --all
   

   If agents are not installed up front, they are lazily installed when creating a session.

5. Install desktop dependencies (optional, Linux only)

   If you want to use /v1/desktop/*, install the desktop runtime packages first:

   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.

6. Create a session

   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);
   
7. Send a message

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

   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();
   
9. 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

Configure in-memory, Rivet Actor state, IndexedDB, SQLite, and Postgres persistence.

Deploy to a Sandbox

Deploy your agent to E2B, Daytona, Docker, Vercel, or Cloudflare.

SDK Overview

Use the latest TypeScript SDK API.