Quickstart

1

Install skill (optional)

npx
bunx

npx 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
E2B
Daytona
Docker

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

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

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

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
npx
bunx
npm i -g
bun add -g
Node.js (local)
Bun (local)
Build from source

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

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

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

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

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
curl
CLI

import { SandboxAgent } from "sandbox-agent";

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

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.

Getting started

Agent

System

Reference

Next steps

Session Persistence

Deploy to a Sandbox

SDK Overview