diff --git a/docs.json b/docs.json index a477a3a9..0fa2c019 100644 --- a/docs.json +++ b/docs.json @@ -56,6 +56,7 @@ "docs/agents/amp", "docs/agents/claude-code", "docs/agents/codex", + "docs/agents/sandbox-agent-sdk", { "group": "OpenClaw", "icon": "https://mintlify.s3.us-west-1.amazonaws.com/e2b-openclaw-icon/images/icons/openclaw.svg", diff --git a/docs/agents/sandbox-agent-sdk.mdx b/docs/agents/sandbox-agent-sdk.mdx new file mode 100644 index 00000000..43441717 --- /dev/null +++ b/docs/agents/sandbox-agent-sdk.mdx @@ -0,0 +1,102 @@ +--- +title: "Sandbox Agent SDK" +description: "Run Sandbox Agent inside an E2B sandbox and control it from a local Node.js script." +--- + +This guide shows how to run [Sandbox Agent](https://github.com/rivet-dev/sandbox-agent) inside an E2B sandbox and control it with the [Sandbox Agent SDK](https://sandboxagent.dev/docs/sdk-overview). + +Sandbox Agent lets you run coding agents in sandboxes and control them from your own backend over HTTP. + +- **Universal Agent API** - A single interface to manage Claude Code, Codex, OpenCode, Cursor, Amp, and Pi with full feature coverage across every supported agent. +- **Universal Session Schema** - A standardized schema that normalizes all agent event formats into a consistent structure for storage and replay. +- **Server or SDK Mode** - Run as a standalone HTTP server or integrate natively using the TypeScript SDK. + +## Workflow overview + +- A local Node.js script starts an E2B sandbox and boots the Sandbox Agent server inside it. +- The script opens a session, sends a prompt to an agent (Claude in this example), and prints the response. +- When the script exits, the sandbox is destroyed. + +## Prerequisites + +- `E2B_API_KEY` +- At least one provider key: `OPENAI_API_KEY`, `CODEX_API_KEY`, or `ANTHROPIC_API_KEY` + +## Setup + +Install dependencies: + +```bash +npm install sandbox-agent dotenv tsx @e2b/code-interpreter +``` + +Create a `.env` file: + +```bash +E2B_API_KEY=your_e2b_api_key +ANTHROPIC_API_KEY=your_anthropic_api_key +# OPENAI_API_KEY=your_openai_api_key +``` + +Create `index.ts` with the snippets below, then run: + +```bash +node --import tsx index.ts +``` + +## Code snippets + +Forward your provider credentials into the sandbox: + +```ts +import "dotenv/config"; +const envs: Record = {}; +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; +``` + +Start Sandbox Agent with the E2B provider: + +```ts +import { SandboxAgent } from 'sandbox-agent'; +import { e2b } from 'sandbox-agent/e2b'; + +const sdk = await SandboxAgent.start({ + sandbox: e2b({ + create: { envs }, + }) +}); + +// The printed inspector URL is where you can open +// the Sandbox Agent inspector UI. +console.log(`Inspector URL: ${sdk.inspectorUrl}`); +``` + +Send a prompt, and stream events: + +```ts +const session = await sdk.createSession({ agent: 'claude' }); +const off = session.onEvent((event) => { + console.log(`[event] from ${event.sender}`, event.payload); +}); +await session.prompt([ + { type: 'text', text: 'Summarize this repository' } +]); +off(); +``` + +Read more about [Sessions and Events](https://sandboxagent.dev/docs/agent-sessions). + +Finally, once done, destroy the sandbox: + +```ts +await sdk.destroySandbox(); +``` + +## Customize the agent + +To use a different agent, update the `agent` value in `createSession` (for example, `codex`) and ensure the corresponding provider credentials are available in the environment. + +## Full example + +See the complete project here in the [e2b-cookbook repo](https://github.com/rivet-dev/e2b-cookbook/tree/main/examples/sandbox-agent-sdk).