mcpField
S
sandbox-agent

sandbox-agent

github.com/rivet-devAgent workflows4410.6k installsUpdated 1d ago
Repository

About sandbox-agent

Sandbox Agent is an API and SDK for orchestrating coding agents in sandboxed environments. This skill provides setup and usage guidance for developers working with agents, sandbox providers, and the Sandbox Agent service.

Key features

  1. 01Configure coding agents and sandbox providers
  2. 02Start or connect to the service
  3. 03Create sessions and send prompts
  4. 04Read session events
  5. 05Test with a mock agent
  6. 06Prepare structured troubleshooting reports

Use cases

  1. 01Set up a coding-agent session in a sandbox
  2. 02Test SDK integrations without provider API keys
  3. 03Connect a client to a deployed Sandbox Agent server
  4. 04Collect details for reporting a problem

MCP support

The reference documents MCP server configuration endpoints, including reading and updating MCP settings. It does not describe an MCP server interface for this skill.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/rivet-dev/skills --skill sandbox-agent

After installing, type/sandbox-agentin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
agent-sessions.md
references/agents/
amp.md
claude.md
codex.md
cursor.md
opencode.md
pi.md
references/ai/
llms-txt.md
references/api-reference/
authentication.md
index.md
references/api-reference/operations/
delete_v1_acp.md
delete_v1_config_mcp.md
delete_v1_config_skills.md
delete_v1_desktop_recording.md
delete_v1_fs_entry.md
delete_v1_process.md
get_v1_acp_servers.md
get_v1_acp.md
get_v1_agent.md
get_v1_agents.md
get_v1_config_mcp.md
get_v1_config_skills.md
get_v1_desktop_clipboard.md
get_v1_desktop_display_info.md
get_v1_desktop_mouse_position.md
get_v1_desktop_recording_download.md
get_v1_desktop_recording.md
get_v1_desktop_recordings.md
get_v1_desktop_screenshot_region.md
get_v1_desktop_screenshot.md

Details

From the project README

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 skill (optional)
npx
npx skills add rivet-dev/skills -s sandbox-agent
bunx
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
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.5.3-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.

Run the server
curl

Install and run the binary directly.

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.

npx @sandbox-agent/[email protected] server --no-token --host 0.0.0.0 --port 2468
bunx

Run without installing globally.

bunx @sandbox-agent/[email protected] server --no-token --host 0.0.0.0 --port 2468
npm i -g

Install globally, then run.

npm install -g @sandbox-agent/[email protected]
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
bun add -g

Install globally, then run.

bun add -g @sandbox-agent/[email protected]
# 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 [email protected]

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 [email protected]
# 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.

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.

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.

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);
Send a message
const result = await session.prompt([
  { type: "text", text: "Summarize the repository and suggest next steps." },
]);

console.log(result.stopReason);
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();
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.

Sandbox Agent Inspector

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.

Reference Map

Agents
AI
Api Reference
Deploy
General

Comments

Markdown supported