内容摘录
<p align="center">
<img src=".github/media/banner.png" alt="Sandbox Agent SDK" />
</p>
<h3 align="center">Run Coding Agents in Sandboxes. Control Them Over HTTP.</h3>
<p align="center">
A server that runs inside your sandbox. Your app connects remotely to control Claude Code, Codex, OpenCode, Cursor, Amp, or Pi — streaming events, handling permissions, managing sessions.
</p>
<p align="center">
<a href="https://sandboxagent.dev/docs">Documentation</a> — <a href="https://sandboxagent.dev/docs/api-reference">API Reference</a> — <a href="https://rivet.dev/discord">Discord</a>
</p>
<p align="center">
<em><strong>Experimental:</strong> <a href="./gigacode/">Gigacode</a> — use OpenCode's TUI with any coding agent.</em>
</p>
Why Sandbox Agent?
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:
**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.
**Every coding agent is different** — Claude Code, Codex, OpenCode, Cursor, Amp, and Pi 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.
**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.
Features
**Universal Agent API**: Single interface to control Claude Code, Codex, OpenCode, Cursor, Amp, and Pi with full feature coverage
**Universal Session Schema**: Standardized schema that normalizes all agent event formats for storage and replay
**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
**OpenCode SDK & UI Support** *(Experimental)*: Connect OpenCode CLI, SDK, or web UI to control agents through familiar OpenCode tooling
Architecture
!Agent Architecture Diagram
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
Components
| Component | Description |
|-----------|-------------|
| **Server** | Rust daemon (sandbox-agent server) exposing the HTTP + SSE API |
| **SDK** | TypeScript client with embedded and server modes |
| **Inspector** | Built-in UI at inspecting sessions and events |
| **CLI** | sandbox-agent (same binary, plus npm wrapper) mirrors the HTTP endpoints |
Get Started
Choose the installation method that works best for your use case.
Skill
Install skill with:
TypeScript SDK
Import the SDK directly into your Node or browser application. Full type safety and streaming support.
**Install**
**Setup**
Local (embedded mode):
Remote (server mode):
**API Overview**
permissionMode: "acceptEdits" passes through to Claude, auto-approves file changes for Codex, and is treated as default for other agents.
SDK documentation — Building a Chat UI — Managing Sessions
HTTP Server
Run as an HTTP server and connect from any language. Deploy to E2B, Daytona, Vercel, or your own infrastructure.
Optional: preinstall agent binaries (no server required; they will be installed lazily on first use if you skip this):
To disable auth locally:
Quickstart — Deployment guides
CLI
Install the CLI wrapper (optional but convenient):
Create a session and send a message:
You can also use npx like:
CLI documentation
Inspector
Debug sessions and events with the built-in Inspector UI (e.g., http://localhost:2468/ui/).
!Sandbox Agent Inspector
Inspector documentation
OpenAPI Specification
Explore API — View Specification
Tip: Extract credentials
Often you need to use your personal API tokens to test agents on sandboxes:
This prints environment variables for your OpenAI/Anthropic/etc API keys to test with Sandbox Agent SDK.
FAQ
<details>
<summary><strong>Does this replace the Vercel AI SDK?</strong></summary>
No, they're complementary. AI SDK is for building chat interfaces and calling LLMs. This SDK is for controlling autonomous coding agents that write code and run commands. Use AI SDK for your UI, use this when you need an agent to actually code.
</details>
<details>
<summary><strong>Which coding agents are supported?</strong></summary>
Claude Code, Codex, OpenCode, Cursor, Amp, and Pi. The SDK normalizes their APIs so you can swap between them without changing your code.
</details>
<details>
<summary><strong>How is session data persisted?</strong></summary>
This SDK does not handle persisting session data. Events stream in a universal JSON schema that you can persist anywhere. See Managing Sessions for patterns using Postgres or Rivet Actors.
</details>
<details>
<summary><strong>Can I run this locally or does it require a sandbox provider?</strong></summary>
Both. Run locally for development, deploy to E2B, Daytona, or Vercel Sandboxes for production.
</details>
<details>
<summary><strong>Does it support [platform]?</strong></summary>
The server is a single Rust binary that runs anywhere with a curl install. If your platform can run Linux binaries (Docker, VMs, etc.), it works. See the deployment guides for E2B, D…