A server that runs inside your sandbox. Your app connects remotely to control Claude Code, Codex, OpenCode, or Amp — streaming events, handling permissions, managing sessions.

Documentation — API Reference — Discord

Running coding agents remotely is hard. Existing SDKs assume local execution, SSH breaks TTY handling and streaming, and every agent has a different API. Building from scratch means reimplementing everything for each coding agent.

Sandbox Agent solves three problems:

1. Coding agents need sandboxes — You can't let AI execute arbitrary code on your production servers. Coding agents need isolated environments, but existing SDKs assume local execution. Sandbox Agent is a server that runs inside the sandbox and exposes HTTP/SSE.

2. Every coding agent is different — Claude Code, Codex, OpenCode, and Amp each have proprietary APIs, event formats, and behaviors. Swapping agents means rewriting your integration. Sandbox Agent provides one HTTP API — write your code once, swap agents with a config change.

3. Sessions are ephemeral — Agent transcripts live in the sandbox. When the process ends, you lose everything. Sandbox Agent streams events in a universal schema to your storage. Persist to Postgres, ClickHouse, or Rivet. Replay later, audit everything.

• Universal Agent API: Single interface to control Claude Code, Codex, OpenCode, and Amp with full feature coverage
• Streaming Events: Real-time SSE stream of everything the agent does — tool calls, permission requests, file edits, and more
• Universal Session Schema: Standardized schema that normalizes all agent event formats for storage and replay
• Human-in-the-Loop: Approve or deny tool executions and answer agent questions remotely over HTTP
• Automatic Agent Installation: Agents are installed on-demand when first used — no setup required
• Runs Inside Any Sandbox: Lightweight static Rust binary. One curl command to install inside E2B, Daytona, Vercel Sandboxes, or Docker
• Server or SDK Mode: Run as an HTTP server or embed with the TypeScript SDK
• OpenAPI Spec: Well documented and easy to integrate from any language

The Sandbox Agent acts as a universal adapter between your client application and various coding agents. Each agent has its own adapter that handles the translation between the universal API and the agent-specific interface.

• Embedded Mode: Runs agents locally as subprocesses
• Server Mode: Runs as HTTP server from any sandbox provider

Architecture documentation

Choose the installation method that works best for your use case.

Install skill with:

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

Import the SDK directly into your Node or browser application. Full type safety and streaming support.

Install

npm install sandbox-agent

Setup

Local (embedded mode):

import { SandboxAgent } from "sandbox-agent";

const client = await SandboxAgent.start();

Remote (server mode):

import { SandboxAgent } from "sandbox-agent";

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

API Overview

const agents = await client.listAgents();

await client.createSession("demo", {
  agent: "codex",
  agentMode: "default",
  permissionMode: "plan",
});

await client.postMessage("demo", { message: "Hello from the SDK." });

for await (const event of client.streamEvents("demo", { offset: 0 })) {
  console.log(event.type, event.data);
}

SDK documentation — Building a Chat UI — Managing Sessions

Run as an HTTP server and connect from any language. Deploy to E2B, Daytona, Vercel, or your own infrastructure.

# Install it
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
# Run it
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468

Optional: preinstall agent binaries (no server required; they will be installed lazily on first use if you skip this):

sandbox-agent install-agent claude
sandbox-agent install-agent codex
sandbox-agent install-agent opencode
sandbox-agent install-agent amp

To disable auth locally:

sandbox-agent server --no-token --host 127.0.0.1 --port 2468

Quickstart — Deployment guides

Install the CLI wrapper (optional but convenient):

npm install -g @sandbox-agent/cli

Create a session and send a message:

sandbox-agent api sessions create my-session --agent codex --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
sandbox-agent api sessions send-message-stream my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"

You can also use npx like:

CLI documentation

Debug sessions and events with the Inspector UI.

Inspector documentation

Explore API — View Specification

All events follow a session transcript schema that normalizes differences between agents.

Often you need to use your personal API tokens to test agents on sandboxes:

sandbox-agent credentials extract-env --export

This prints environment variables for your OpenAI/Anthropic/etc API keys to test with Sandbox Agent SDK.

Works with your stack: