From 6aab65bcaac1c4bec96641633ffff033876120e2 Mon Sep 17 00:00:00 2001 From: abcxff <79597906+abcxff@users.noreply.github.com> Date: Wed, 25 Mar 2026 19:17:39 -0400 Subject: [PATCH 1/4] feat(docs): sandbox agent sdk + e2b usage docs --- docs.json | 1 + docs/agents/sandbox-agent-sdk.mdx | 90 +++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) create mode 100644 docs/agents/sandbox-agent-sdk.mdx 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..3199b914 --- /dev/null +++ b/docs/agents/sandbox-agent-sdk.mdx @@ -0,0 +1,90 @@ +--- +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). + +## 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 +``` + +Create a `.env` file: + +```bash +E2B_API_KEY=your_e2b_api_key +OPENAI_API_KEY=your_openai_api_key +# CODEX_API_KEY=your_codex_api_key +# ANTHROPIC_API_KEY=your_anthropic_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 +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; +if (process.env.CODEX_API_KEY) envs.CODEX_API_KEY = process.env.CODEX_API_KEY; +if (!envs.CODEX_API_KEY && envs.OPENAI_API_KEY) envs.CODEX_API_KEY = envs.OPENAI_API_KEY; +if (!envs.OPENAI_API_KEY && !envs.CODEX_API_KEY && !envs.ANTHROPIC_API_KEY) { + throw new Error('Set OPENAI_API_KEY/CODEX_API_KEY or ANTHROPIC_API_KEY'); +} +``` + +Start Sandbox Agent with the E2B provider and open a session: + +```ts +import { SandboxAgent } from 'sandbox-agent'; +import { e2b } from 'sandbox-agent/e2b'; + +const sdk = await SandboxAgent.start({ + sandbox: e2b({ + create: { envs }, + }) +}); + +const session = await sdk.createSession({ agent: 'claude' }); +console.log(`Inspector URL: ${sdk.inspectorUrl}`); +``` + +Send a prompt, then clean up the sandbox: + +```ts +const response = await session.prompt([ + { type: 'text', text: 'Summarize this repository' }, +]); +console.log(response.stopReason); + +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). From d093aef0c0cf9e684edc8b2620b5056be60fc975 Mon Sep 17 00:00:00 2001 From: abcxff <79597906+abcxff@users.noreply.github.com> Date: Wed, 25 Mar 2026 20:58:54 -0400 Subject: [PATCH 2/4] chore(docs): cleanup sandbox-agent-sdk --- docs/agents/sandbox-agent-sdk.mdx | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/agents/sandbox-agent-sdk.mdx b/docs/agents/sandbox-agent-sdk.mdx index 3199b914..50bdff11 100644 --- a/docs/agents/sandbox-agent-sdk.mdx +++ b/docs/agents/sandbox-agent-sdk.mdx @@ -29,7 +29,6 @@ Create a `.env` file: ```bash E2B_API_KEY=your_e2b_api_key OPENAI_API_KEY=your_openai_api_key -# CODEX_API_KEY=your_codex_api_key # ANTHROPIC_API_KEY=your_anthropic_api_key ``` @@ -66,18 +65,22 @@ const sdk = await SandboxAgent.start({ }) }); -const session = await sdk.createSession({ agent: 'claude' }); console.log(`Inspector URL: ${sdk.inspectorUrl}`); ``` -Send a prompt, then clean up the sandbox: +Send a prompt, and stream events: ```ts -const response = await session.prompt([ - { type: 'text', text: 'Summarize this repository' }, -]); -console.log(response.stopReason); +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: 'Explain this repository' }]) +off(); +``` +Finally, once done, destroy the sandbox: +```ts await sdk.destroySandbox(); ``` From 5d4faab9aeeff4bace680b2c26cc08c4632ed94c Mon Sep 17 00:00:00 2001 From: abcxff <79597906+abcxff@users.noreply.github.com> Date: Wed, 25 Mar 2026 21:13:55 -0400 Subject: [PATCH 3/4] feat(docs): sandbox-agent-sdk docs --- docs/agents/sandbox-agent-sdk.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/agents/sandbox-agent-sdk.mdx b/docs/agents/sandbox-agent-sdk.mdx index 50bdff11..f96b2343 100644 --- a/docs/agents/sandbox-agent-sdk.mdx +++ b/docs/agents/sandbox-agent-sdk.mdx @@ -53,7 +53,7 @@ if (!envs.OPENAI_API_KEY && !envs.CODEX_API_KEY && !envs.ANTHROPIC_API_KEY) { } ``` -Start Sandbox Agent with the E2B provider and open a session: +Start Sandbox Agent with the E2B provider: ```ts import { SandboxAgent } from 'sandbox-agent'; @@ -65,6 +65,8 @@ const sdk = await SandboxAgent.start({ }) }); +// The printed inspector URL is where you can open +// the Sandbox Agent inspector UI. console.log(`Inspector URL: ${sdk.inspectorUrl}`); ``` @@ -75,7 +77,9 @@ 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: 'Explain this repository' }]) +await session.prompt([ + { type: 'text', text: 'Summarize this repository' } +]); off(); ``` From 2cb57b3c9bd3031e6a065ae1f7b1d041ce92cd7d Mon Sep 17 00:00:00 2001 From: abcxff <79597906+abcxff@users.noreply.github.com> Date: Wed, 25 Mar 2026 21:39:35 -0400 Subject: [PATCH 4/4] feat(docs): sandbox-agent-sdk docs --- docs/agents/sandbox-agent-sdk.mdx | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/agents/sandbox-agent-sdk.mdx b/docs/agents/sandbox-agent-sdk.mdx index f96b2343..43441717 100644 --- a/docs/agents/sandbox-agent-sdk.mdx +++ b/docs/agents/sandbox-agent-sdk.mdx @@ -5,6 +5,12 @@ description: "Run Sandbox Agent inside an E2B sandbox and control it from a loca 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. @@ -21,15 +27,15 @@ This guide shows how to run [Sandbox Agent](https://github.com/rivet-dev/sandbox Install dependencies: ```bash -npm install sandbox-agent dotenv tsx +npm install sandbox-agent dotenv tsx @e2b/code-interpreter ``` Create a `.env` file: ```bash E2B_API_KEY=your_e2b_api_key -OPENAI_API_KEY=your_openai_api_key -# ANTHROPIC_API_KEY=your_anthropic_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: @@ -43,14 +49,10 @@ node --import tsx index.ts 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; -if (process.env.CODEX_API_KEY) envs.CODEX_API_KEY = process.env.CODEX_API_KEY; -if (!envs.CODEX_API_KEY && envs.OPENAI_API_KEY) envs.CODEX_API_KEY = envs.OPENAI_API_KEY; -if (!envs.OPENAI_API_KEY && !envs.CODEX_API_KEY && !envs.ANTHROPIC_API_KEY) { - throw new Error('Set OPENAI_API_KEY/CODEX_API_KEY or ANTHROPIC_API_KEY'); -} ``` Start Sandbox Agent with the E2B provider: @@ -73,7 +75,7 @@ console.log(`Inspector URL: ${sdk.inspectorUrl}`); Send a prompt, and stream events: ```ts -const session = await sdk.createSession({ agent: "claude" }); +const session = await sdk.createSession({ agent: 'claude' }); const off = session.onEvent((event) => { console.log(`[event] from ${event.sender}`, event.payload); }); @@ -83,7 +85,10 @@ await session.prompt([ off(); ``` +Read more about [Sessions and Events](https://sandboxagent.dev/docs/agent-sessions). + Finally, once done, destroy the sandbox: + ```ts await sdk.destroySandbox(); ```