From 444e443dadaac28de338a267e0b1de695ee40735 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Fri, 9 Jan 2026 16:12:25 +0100 Subject: [PATCH 1/7] Update home page --- docs.mdx | 54 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/docs.mdx b/docs.mdx index a330775..57cbfc9 100644 --- a/docs.mdx +++ b/docs.mdx @@ -4,37 +4,43 @@ sidebarTitle: Home icon: house --- -import { Concepts } from '/snippets/Concepts.jsx'; -import { CodeInterpreting } from '/snippets/CodeInterpreting.jsx'; import { Quickstart } from '/snippets/Quickstart.jsx'; +import { CodeInterpreting } from '/snippets/CodeInterpreting.jsx'; +import { Examples } from '/snippets/Examples.jsx'; +import { Reference } from '/snippets/Reference.jsx'; -Here you'll find all the guides, concepts, and SDK references for developing with E2B. +## What is E2B? - -```bash JavaScript & TypeScript -npm i @e2b/code-interpreter -``` -```bash Python -pip install e2b-code-interpreter -``` - +E2B provides isolated sandboxes that let agents safely execute code, process data, and run tools. Our [SDKs]() make it easy to start and manage these environments. -## What is E2B? -E2B is an [open-source](https://github.com/e2b-dev) infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. -To start and control sandboxes, use our [Python SDK](https://pypi.org/project/e2b/) or [JavaScript SDK](https://www.npmjs.com/package/e2b). +## E2B Building Blocks + +A quick overview of the core building blocks you'll interact with when using E2B. + +- [**Sandbox**]() — A fast, secure Linux VM created on demand for your agent + +- [**Template**]() — Defines what environment a sandbox starts with + +## How to use the docs + +The documentation is split into three main sections: + +- [**Quickstart**](#quickstart) — Step-by-step tutorials that walk you through spinning up your first E2B sandboxes. + +- [**Examples**](#examples) — In-depth tutorials focused on specific use cases. Pick the topics that match what you're building. + +- [**API/SDK Reference**](https://e2b.dev/docs/sdk-reference) — A complete technical reference for every feature, component, and configuration option. + +
-Some of the typical use cases for E2B are AI data analysis or visualization, running AI-generated code of various languages, playground for coding agents, environment for codegen evals, or running full AI-generated apps like in [Fragments](https://github.com/e2b-dev/fragments). +## 🚀 Quickstart. -### Under the hood -The E2B Sandbox is a small isolated VM the can be started very quickly (~150ms). You can think of it as a small computer for the AI model. You can run many sandboxes at once. Typically, you run separate sandbox for each LLM, user, or AI agent session in your app. -For example, if you were building an AI data analysis chatbot, you would start the sandbox for every user session. + -## Quickstart - +
-## Code interpreting with AI - +## 🧠 Examples -## Learn the core concepts - + +
\ No newline at end of file From b13e2674fd785ba7ca78edee447ce22292d3e2c6 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Fri, 9 Jan 2026 16:12:48 +0100 Subject: [PATCH 2/7] New docs structure --- docs.json | 147 +-------- docs/faq.mdx | 9 + docs/sandbox/executing-code.mdx | 9 + docs/sandbox/intro.mdx | 9 + docs/sandbox/persistence.mdx | 296 +----------------- docs/sandbox/reading-output.mdx | 9 + docs/sandbox/security.mdx | 9 + docs/templates/intro.mdx | 9 + .../ai-data-analysis-visualization.mdx | 9 + docs/use-cases/deep-research-agents.mdx | 9 + docs/use-cases/linux-desktop.mdx | 9 + docs/use-cases/reinforcement-learning.mdx | 9 + docs/use-cases/vibe-coding.mdx | 9 + 13 files changed, 118 insertions(+), 424 deletions(-) create mode 100644 docs/faq.mdx create mode 100644 docs/sandbox/executing-code.mdx create mode 100644 docs/sandbox/intro.mdx create mode 100644 docs/sandbox/reading-output.mdx create mode 100644 docs/sandbox/security.mdx create mode 100644 docs/templates/intro.mdx create mode 100644 docs/use-cases/ai-data-analysis-visualization.mdx create mode 100644 docs/use-cases/deep-research-agents.mdx create mode 100644 docs/use-cases/linux-desktop.mdx create mode 100644 docs/use-cases/reinforcement-learning.mdx create mode 100644 docs/use-cases/vibe-coding.mdx diff --git a/docs.json b/docs.json index f1410c9..0d035fa 100644 --- a/docs.json +++ b/docs.json @@ -36,158 +36,39 @@ "docs/quickstart/install-custom-packages" ] }, - "docs/api-key", - "docs/cookbook", - "docs/support" + "docs/api-key" ] }, { - "group": "Code Interpreting", + "group": "Use Case Examples", "pages": [ - { - "group": "Analyze data with AI", - "pages": [ - "docs/code-interpreting/analyze-data-with-ai", - "docs/code-interpreting/analyze-data-with-ai/pre-installed-libraries" - ] - }, - { - "group": "Charts & visualizations", - "pages": [ - "docs/code-interpreting/create-charts-visualizations", - "docs/code-interpreting/create-charts-visualizations/static-charts", - "docs/code-interpreting/create-charts-visualizations/interactive-charts" - ] - }, - "docs/code-interpreting/streaming", - { - "group": "Supported languages", - "pages": [ - "docs/code-interpreting/supported-languages", - "docs/code-interpreting/supported-languages/python", - "docs/code-interpreting/supported-languages/javascript", - "docs/code-interpreting/supported-languages/r", - "docs/code-interpreting/supported-languages/java", - "docs/code-interpreting/supported-languages/bash" - ] - } + "docs/use-cases/linux-desktop", + "docs/use-cases/deep-research-agents", + "docs/use-cases/ai-data-analysis-visualization", + "docs/use-cases/reinforcement-learning", + "docs/use-cases/vibe-coding" ] }, { "group": "Sandbox", "pages": [ - "docs/sandbox", - "docs/sandbox/lifecycle-events-api", - "docs/sandbox/lifecycle-events-webhooks", + "docs/sandbox/intro", + "docs/sandbox/executing-code", + "docs/sandbox/reading-output", "docs/sandbox/persistence", - "docs/sandbox/metrics", - "docs/sandbox/metadata", - "docs/sandbox/environment-variables", - "docs/sandbox/list", - "docs/sandbox/connect", - "docs/sandbox/internet-access", - "docs/sandbox/connect-bucket", - "docs/sandbox/rate-limits", - "docs/sandbox/secured-access" + "docs/sandbox/security" ] }, { "group": "Templates", "pages": [ - "docs/template/quickstart", - "docs/template/how-it-works", - "docs/template/user-and-workdir", - "docs/template/caching", - "docs/template/base-image", - "docs/template/private-registries", - "docs/template/defining-template", - "docs/template/start-ready-command", - "docs/template/build", - "docs/template/logging", - "docs/template/error-handling", - { - "group": "Examples", - "pages": [ - "docs/template/examples/nextjs", - "docs/template/examples/nextjs-bun", - "docs/template/examples/expo", - "docs/template/examples/desktop", - "docs/template/examples/claude-code" - ] - }, - "docs/template/migration-v2", - { - "group": "Legacy Docs", - "pages": [ - "docs/sandbox-template", - "docs/sandbox-template/start-cmd", - "docs/sandbox-template/ready-cmd", - "docs/sandbox-template/customize-cpu-ram" - ] - } - ] - }, - { - "group": "Filesystem", - "pages": [ - "docs/filesystem", - "docs/filesystem/read-write", - "docs/filesystem/info", - "docs/filesystem/watch", - "docs/filesystem/upload", - "docs/filesystem/download" + "docs/templates/intro" ] }, { - "group": "Commands", + "group": "FAQ", "pages": [ - "docs/commands", - "docs/commands/streaming", - "docs/commands/background" - ] - }, - { - "group": "MCP Gateway", - "pages": [ - "docs/mcp", - "docs/mcp/quickstart", - "docs/mcp/available-servers", - "docs/mcp/custom-templates", - "docs/mcp/custom-servers", - "docs/mcp/examples" - ] - }, - { - "group": "CLI", - "pages": [ - "docs/cli", - "docs/cli/auth", - "docs/cli/list-sandboxes", - "docs/cli/shutdown-sandboxes" - ] - }, - { - "group": "Deployment", - "pages": ["docs/byoc"] - }, - { - "group": "Migration", - "pages": ["docs/migration/v2"] - }, - { - "group": "Troubleshooting", - "pages": [ - { - "group": "SDKs", - "pages": ["docs/troubleshooting/sdks/workers-edge-runtime"] - }, - { - "group": "Templates", - "pages": [ - "docs/troubleshooting/templates/build-authentication-error", - "docs/troubleshooting/templates/49999-port-not-open" - ] - } + "docs/faq" ] } ] diff --git a/docs/faq.mdx b/docs/faq.mdx new file mode 100644 index 0000000..15c02a2 --- /dev/null +++ b/docs/faq.mdx @@ -0,0 +1,9 @@ +--- +title: "FAQ" +description: "Frequently asked questions about E2B sandboxes, templates, pricing, security, performance, and common troubleshooting scenarios." +icon: "circle-question" +--- + +# FAQ + +Content coming soon. diff --git a/docs/sandbox/executing-code.mdx b/docs/sandbox/executing-code.mdx new file mode 100644 index 0000000..9af3719 --- /dev/null +++ b/docs/sandbox/executing-code.mdx @@ -0,0 +1,9 @@ +--- +title: "Executing Code" +description: "Run code and shell commands in E2B sandboxes with support for multiple languages, streaming output, background processes, and real-time execution control." +icon: "terminal" +--- + +# Executing Code + +Content coming soon. diff --git a/docs/sandbox/intro.mdx b/docs/sandbox/intro.mdx new file mode 100644 index 0000000..c543838 --- /dev/null +++ b/docs/sandbox/intro.mdx @@ -0,0 +1,9 @@ +--- +title: "Sandbox Intro" +description: "E2B sandboxes provide secure, isolated cloud environments for running untrusted code with full control over execution, filesystem, and networking." +icon: "cube" +--- + +# Sandbox Intro + +Content coming soon. diff --git a/docs/sandbox/persistence.mdx b/docs/sandbox/persistence.mdx index 29f3939..0f4bc88 100644 --- a/docs/sandbox/persistence.mdx +++ b/docs/sandbox/persistence.mdx @@ -1,295 +1,9 @@ --- -title: "Sandbox persistence" -sidebarTitle: Persistence +title: "Persistence" +description: "Manage persistent storage in E2B sandboxes with volumes that survive across sandbox sessions, enabling stateful workflows and long-term data retention." +icon: "database" --- - -Sandbox persistence is currently in public beta: -1. Consider [some limitations](#limitations-while-in-beta). -2. The persistence is free for all users during the beta. - +# Persistence -The sandbox persistence allows you to pause your sandbox and resume it later from the same state it was in when you paused it. - -This includes not only state of the sandbox's filesystem but also the sandbox's memory. This means all running processes, loaded variables, data, etc. - -## Sandbox State Transitions - -Understanding how sandboxes transition between different states is crucial for managing their lifecycle effectively. Here's a diagram showing the possible state transitions: - - - - - -### State descriptions - -- **Running**: The sandbox is actively running and can execute code. This is the initial state after creation. -- **Paused**: The sandbox execution is suspended but its state is preserved. -- **Killed**: The sandbox is terminated and all resources are released. This is a terminal state. - -### Changing sandbox's state - - -```js JavaScript & TypeScript -import { Sandbox } from '@e2b/code-interpreter' - -const sandbox = await Sandbox.create() // Starts in Running state - -// Pause the sandbox -await sandbox.betaPause() // Running → Paused - -// Resume the sandbox -await sandbox.connect() // Running/Paused → Running - -// Kill the sandbox (from any state) -await sandbox.kill() // Running/Paused → Killed -``` - -```python Python -from e2b_code_interpreter import Sandbox - -sandbox = Sandbox.create() # Starts in Running state - -# Pause the sandbox -sandbox.betaPause() # Running → Paused - -# Resume the sandbox -sandbox.connect() # Running/Paused → Running - -# Kill the sandbox (from any state) -sandbox.kill() # Running/Paused → Killed -``` - - -## Pausing sandbox -When you pause a sandbox, both the sandbox's filesystem and memory state will be saved. This includes all the files in the sandbox's filesystem and all the running processes, loaded variables, data, etc. - - -```js JavaScript & TypeScript highlight={8-9} -import { Sandbox } from '@e2b/code-interpreter' - -const sbx = await Sandbox.create() -console.log('Sandbox created', sbx.sandboxId) - -// Pause the sandbox -// You can save the sandbox ID in your database to resume the sandbox later -await sbx.betaPause() -console.log('Sandbox paused', sbx.sandboxId) -``` -```python Python highlight={8-9} -from e2b_code_interpreter import Sandbox - -sbx = Sandbox.create() -print('Sandbox created', sbx.sandbox_id) - -# Pause the sandbox -# You can save the sandbox ID in your database to resume the sandbox later -sbx.beta_pause() -print('Sandbox paused', sbx.sandbox_id) -``` - - - -## Resuming sandbox -When you resume a sandbox, it will be in the same state it was in when you paused it. -This means that all the files in the sandbox's filesystem will be restored and all the running processes, loaded variables, data, etc. will be restored. - - -```js JavaScript & TypeScript highlight={12-13} -import { Sandbox } from '@e2b/code-interpreter' - -const sbx = await Sandbox.create() -console.log('Sandbox created', sbx.sandboxId) - -// Pause the sandbox -// You can save the sandbox ID in your database to resume the sandbox later -await sbx.betaPause() -console.log('Sandbox paused', sbx.sandboxId) - -// Connect to the sandbox (it will automatically resume the sandbox, if paused) -const sameSbx = await sbx.connect() -console.log('Connected to the sandbox', sameSbx.sandboxId) -``` -```python Python highlight={12-13} -from e2b_code_interpreter import Sandbox - -sbx = Sandbox.create() -print('Sandbox created', sbx.sandbox_id) - -# Pause the sandbox -# You can save the sandbox ID in your database to resume the sandbox later -sbx.beta_pause() -print('Sandbox paused', sbx.sandbox_id) - -# Connect to the sandbox (it will automatically resume the sandbox, if paused) -same_sbx = sbx.connect() -print('Connected to the sandbox', same_sbx.sandbox_id) -``` - - -## Listing paused sandboxes -You can list all paused sandboxes by calling the `Sandbox.list` method and supplying the `state` query parameter. -More information about using the method can be found in [List Sandboxes](/docs/sandbox/list). - - -```js JavaScript & TypeScript highlight={4,7} -import { Sandbox, SandboxInfo } from '@e2b/code-interpreter' - -// List all paused sandboxes -const paginator = Sandbox.list({ query: { state: ['paused'] } }) - -// Get the first page of paused sandboxes -const sandboxes = await paginator.nextItems() - -// Get all paused sandboxes -while (paginator.hasNext) { - const items = await paginator.nextItems() - sandboxes.push(...items) -} -``` -```python Python highlight={4,7} -# List all paused sandboxes -from e2b_code_interpreter import Sandbox, SandboxQuery, SandboxState - -paginator = Sandbox.list(SandboxQuery(state=[SandboxState.PAUSED])) - -# Get the first page of paused sandboxes -sandboxes = paginator.next_items() - -# Get all paused sandboxes -while paginator.has_next: - items = paginator.next_items() - sandboxes.extend(items) -``` - - -## Removing paused sandboxes - -You can remove paused sandboxes by calling the `kill` method on the Sandbox instance. - - -```js JavaScript & TypeScript highlight={11,14} -import { Sandbox } from '@e2b/code-interpreter' - -const sbx = await Sandbox.create() -console.log('Sandbox created', sbx.sandboxId) - -// Pause the sandbox -// You can save the sandbox ID in your database to resume the sandbox later -await sbx.betaPause() - -// Remove the sandbox -await sbx.kill() - -// Remove sandbox by id -await Sandbox.kill(sbx.sandboxId) -``` -```python Python highlight={9,12} -from e2b_code_interpreter import Sandbox - -sbx = Sandbox.create() - -# Pause the sandbox -sbx.beta_pause() - -# Remove the sandbox -sbx.kill() - -# Remove sandbox by id -Sandbox.kill(sbx.sandbox_id) -``` - - -## Sandbox's timeout -When you connect to a sandbox, the sandbox's timeout is reset to the default timeout of an E2B sandbox - 5 minutes. - -You can pass a custom timeout to the `Sandbox.connect()`/`Sandbox.connect()` method like this: - - -```js JavaScript & TypeScript -import { Sandbox } from '@e2b/code-interpreter' - -const sbx = await Sandbox.connect(sandboxId, { timeoutMs: 60 * 1000 }) // 60 seconds -``` -```python Python -from e2b_code_interpreter import Sandbox - -sbx = Sandbox.connect(sandbox_id, timeout=60) # 60 seconds -``` - - - -### Auto-pause (beta) - -**Note: Auto-pause is currently in beta and available through `Sandbox.betaCreate()`/`Sandbox.beta_create()` method.** - -Sandboxes can now automatically pause after they time out. When a sandbox is paused, it stops consuming compute but preserves its state. The default inactivity timeout is 10 minutes. You can change the timeout by passing the `timeoutMs`/`timeout` parameter to the `Sandbox.connect()`/`Sandbox.connect()` method. - - -```js JavaScript & TypeScript -import { Sandbox } from '@e2b/code-interpreter' - -// Create sandbox with auto-pause enabled -const sandbox = await Sandbox.betaCreate({ - autoPause: true, - timeoutMs: 10 * 60 * 1000 // Optional: change the default timeout (10 minutes) -}) -``` -```python Python -from e2b_code_interpreter import Sandbox - -# Create sandbox with auto-pause enabled (Beta) -sandbox = Sandbox.beta_create( - auto_pause=True, # Auto-pause after the sandbox times out - timeout=10 * 60, # Optional: change the default timeout (10 minutes) -) -``` - - -The auto-pause is persistent, meaning that if your sandbox resumes and it times out, it will be automatically paused again. - -If you `.kill()` the sandbox, it will be permanently deleted and you won't be able to resume it. - - -```js JavaScript & TypeScript -import { Sandbox } from '@e2b/code-interpreter' - -// Create sandbox with auto-pause enabled (Beta) -const sandbox = await Sandbox.betaCreate({ - autoPause: true // Auto-pause after the sandbox times out -}) -``` -```python Python -from e2b_code_interpreter import Sandbox - -# Create sandbox with auto-pause enabled (Beta) -sandbox = Sandbox.beta_create( - auto_pause=True # Auto-pause after the sandbox times out -) -``` - - -## Network -If you have a service (for example a server) running inside your sandbox and you pause the sandbox, the service won't be accessible from the outside and all the clients will be disconnected. -If you resume the sandbox, the service will be accessible again but you need to connect clients again. - - -## Limitations while in beta - -### Lifecycle duration -- A sandbox can exist for **up to 30 days** from the initial `create` call. -- After 30 days, sandbox data **may be deleted** and the sandbox can no longer be resumed. -- Attempting to resume a deleted or non-existent sandbox will result in: - - `NotFoundError` in the JavaScript SDK - - `NotFoundException` in the Python SDK - -### Pause and resume performance -- Pausing a sandbox takes approximately **4 seconds per 1 GiB of RAM** -- Resuming a sandbox takes approximately **1 second** - -### Continuous runtime limits -- A sandbox can remain running (without being paused) for: - - **24 hours** on the **Pro tier** - - **1 hour** on the **Base tier** -- After a sandbox is paused and resumed, the continuous runtime limit is **reset** -- The **30-day total lifetime limit** still applies regardless of how many times the sandbox is paused or resumed +Content coming soon. diff --git a/docs/sandbox/reading-output.mdx b/docs/sandbox/reading-output.mdx new file mode 100644 index 0000000..66e7384 --- /dev/null +++ b/docs/sandbox/reading-output.mdx @@ -0,0 +1,9 @@ +--- +title: "Reading Output" +description: "Capture stdout, stderr, and exit codes from code execution in E2B sandboxes with support for real-time streaming, line-by-line processing, and buffered output handling." +icon: "scroll" +--- + +# Reading Output + +Content coming soon. diff --git a/docs/sandbox/security.mdx b/docs/sandbox/security.mdx new file mode 100644 index 0000000..50ee389 --- /dev/null +++ b/docs/sandbox/security.mdx @@ -0,0 +1,9 @@ +--- +title: "Security" +description: "Learn about E2B's security model including sandbox isolation, network policies, resource limits, and best practices for running untrusted code safely in production environments." +icon: "shield-halved" +--- + +# Security + +Content coming soon. diff --git a/docs/templates/intro.mdx b/docs/templates/intro.mdx new file mode 100644 index 0000000..f6ca82b --- /dev/null +++ b/docs/templates/intro.mdx @@ -0,0 +1,9 @@ +--- +title: "Templates Intro" +description: "Create custom sandbox templates with pre-installed dependencies, configurations, and tools to quickly spin up consistent development environments for your AI agents." +icon: "layer-group" +--- + +# Templates Intro + +Content coming soon. diff --git a/docs/use-cases/ai-data-analysis-visualization.mdx b/docs/use-cases/ai-data-analysis-visualization.mdx new file mode 100644 index 0000000..2b885e9 --- /dev/null +++ b/docs/use-cases/ai-data-analysis-visualization.mdx @@ -0,0 +1,9 @@ +--- +title: "AI Data Analysis & Visualization" +description: "Enable AI agents to analyze datasets, generate insights, create charts and visualizations, and perform statistical analysis using Python libraries like pandas, matplotlib, and seaborn." +icon: "chart-line" +--- + +# AI Data Analysis & Visualization + +Content coming soon. diff --git a/docs/use-cases/deep-research-agents.mdx b/docs/use-cases/deep-research-agents.mdx new file mode 100644 index 0000000..f8e013b --- /dev/null +++ b/docs/use-cases/deep-research-agents.mdx @@ -0,0 +1,9 @@ +--- +title: "Deep Research Agents" +description: "Build AI agents that perform comprehensive research by executing code, analyzing data, running experiments, and iterating on findings in isolated sandbox environments." +icon: "magnifying-glass-chart" +--- + +# Deep Research Agents + +Content coming soon. diff --git a/docs/use-cases/linux-desktop.mdx b/docs/use-cases/linux-desktop.mdx new file mode 100644 index 0000000..94c9e10 --- /dev/null +++ b/docs/use-cases/linux-desktop.mdx @@ -0,0 +1,9 @@ +--- +title: "Linux Desktop" +description: "Run full Linux desktop environments in E2B sandboxes with GUI support, window management, and remote access capabilities for browser automation, visual testing, and interactive applications." +icon: "desktop" +--- + +# Linux Desktop + +Content coming soon. diff --git a/docs/use-cases/reinforcement-learning.mdx b/docs/use-cases/reinforcement-learning.mdx new file mode 100644 index 0000000..8040ebd --- /dev/null +++ b/docs/use-cases/reinforcement-learning.mdx @@ -0,0 +1,9 @@ +--- +title: "Reinforcement Learning" +description: "Train and evaluate reinforcement learning agents in secure sandbox environments with support for simulation frameworks, custom environments, and parallel training workflows." +icon: "brain-circuit" +--- + +# Reinforcement Learning + +Content coming soon. diff --git a/docs/use-cases/vibe-coding.mdx b/docs/use-cases/vibe-coding.mdx new file mode 100644 index 0000000..363fb86 --- /dev/null +++ b/docs/use-cases/vibe-coding.mdx @@ -0,0 +1,9 @@ +--- +title: "Vibe Coding" +description: "Experience AI-powered coding with real-time code execution, instant feedback, and interactive development where AI agents write, test, and iterate on code in live sandbox environments." +icon: "wand-magic-sparkles" +--- + +# Vibe Coding + +Content coming soon. From 35ed997be2781132205062203e3d8ab427a015e7 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Mon, 12 Jan 2026 12:20:30 +0100 Subject: [PATCH 3/7] Create use case example structure --- docs/use-cases/deep-research-agents.mdx | 55 ++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/docs/use-cases/deep-research-agents.mdx b/docs/use-cases/deep-research-agents.mdx index f8e013b..71f5e8e 100644 --- a/docs/use-cases/deep-research-agents.mdx +++ b/docs/use-cases/deep-research-agents.mdx @@ -4,6 +4,59 @@ description: "Build AI agents that perform comprehensive research by executing c icon: "magnifying-glass-chart" --- -# Deep Research Agents +## Related Guides + + + + Create and manage E2B sandboxes + + + Run code in sandboxes + + + Capture execution results + + + Save data across sessions + + + Create charts from findings + + + Custom sandbox templates + + + +## Project Structure + + +```ts JavaScript && TypeScript +research-agent/ +├── agent/ +│ ├── orchestrator.py // Main agent logic +│ ├── tools.py // Research tools (web search, code execution) +│ └── memory.py // Research state management +├── sandbox/ +│ ├── setup.py // Sandbox initialization +│ └── analysis.py // Data analysis helpers +├── config.py // Configuration (API keys, models) +└── main.py // Entry point +``` +```python Python +research-agent/ +├── agent/ +│ ├── orchestrator.py # Main agent logic +│ ├── tools.py # Research tools (web search, code execution) +│ └── memory.py # Research state management +├── sandbox/ +│ ├── setup.py # Sandbox initialization +│ └── analysis.py # Data analysis helpers +├── config.py # Configuration (API keys, models) +└── main.py # Entry point +``` + +--- + +## Implementation Content coming soon. From ec5b849f65ae3068edc1e7f06e9dfd09a45ecb18 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Tue, 13 Jan 2026 17:16:21 +0100 Subject: [PATCH 4/7] Explain sdk - rough idea --- docs/sdks-explained.mdx | 228 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 docs/sdks-explained.mdx diff --git a/docs/sdks-explained.mdx b/docs/sdks-explained.mdx new file mode 100644 index 0000000..8e90fdb --- /dev/null +++ b/docs/sdks-explained.mdx @@ -0,0 +1,228 @@ +--- +title: "SDKs Explained" +description: "E2B offers three SDK packages, each available in **Python** and **JavaScript/TypeScript**." +icon: "code" +--- + + +**Architecture:** `e2b-code-interpreter` and `e2b-desktop` are built on top of the core `e2b` SDK. All classes, methods, and features from `e2b` are available in the specialized SDKs. + + + + + Core SDK - Foundation + + + e2b + code execution environment + + + e2b + Linux desktop GUI + + + +--- + + +## e2b + +General-purpose sandboxes for running any code, commands, or processes. + +**Use when:** Building custom AI agents, running untrusted code, or need full control over the environment. + +### Installation + + +```bash Python +pip install e2b +``` + +```bash JavaScript +npm install e2b +``` + + +### Quick Start + + +```python Python +from e2b import Sandbox + +# Create sandbox +sbx = Sandbox.create() + +# Run command +result = sbx.commands.run("echo 'Hello from E2B'") +print(result.stdout) + +# Run Python code +result = sbx.commands.run("whoami") +print(result.stdout) +``` + +```typescript JavaScript +import { Sandbox } from 'e2b' + +// Create sandbox +const sbx = await Sandbox.create() + +// Run command +const result = await sbx.commands.run("echo 'Hello from E2B'") +console.log(result.stdout) + +// Run Node.js code +const result2 = await sbx.commands.run("whoami") +console.log(result2.stdout) +``` + + + + Complete API documentation + + +--- + + +## e2b-code-interpreter + +Built on top of `e2b` with added support for multi-language code execution (Python, JavaScript, R, Java, Bash), pre-installed data science libraries, and visualization capabilities. + + +Includes **all features from `e2b`** plus specialized code execution methods and pre-configured environment. + + +**Use when:** Building AI data analysts, code execution environments, or need chart generation. + +### Installation + + +```bash Python +pip install e2b-code-interpreter +``` + +```bash JavaScript +npm install @e2b/code-interpreter +``` + + +### Quick Start + + +```python Python +from e2b_code_interpreter import Sandbox + +# Create code interpreter +sbx = Sandbox.create() + +# Execute code with results +execution = sbx.run_code("print('Hello from E2B'); 2 + 2") + +# Access results +for result in execution.results: + print(result) +``` + +```typescript JavaScript +import { Sandbox } from '@e2b/code-interpreter' + +// Create code interpreter +const sbx = await Sandbox.create() + +// Execute code with results +const execution = await sbx.runCode("console.log('Hello from E2B'); 2 + 2") + +// Access results +execution.results.forEach(result => console.log(result)) +``` + + + + Detailed documentation, examples, and supported languages + + +--- + + +## e2b-desktop + +Built on top of `e2b` with a full Linux desktop environment including GUI, browser, and window management. + + +Includes **all features from `e2b`** plus desktop-specific methods like `getDesktopUrl()` and pre-configured GUI environment. + + +**Use when:** Browser automation, visual testing, or applications requiring a desktop UI. + +### Installation + + +```bash Python +pip install e2b-desktop +``` + +```bash JavaScript +npm install @e2b/desktop +``` + + +### Quick Start + + +```python Python +from e2b_desktop import Sandbox + +# Create desktop sandbox +sbx = Sandbox.create() + +# Get desktop URL +desktop_url = sbx.get_desktop_url() +print(f"Access desktop at: {desktop_url}") + +# Run GUI application +sbx.commands.run("firefox https://example.com") +``` + +```typescript JavaScript +import { Sandbox } from '@e2b/desktop' + +// Create desktop sandbox +const sbx = await Sandbox.create() + +// Get desktop URL +const desktopUrl = await sbx.getDesktopUrl() +console.log(`Access desktop at: ${desktopUrl}`) + +// Run GUI application +await sbx.commands.run('firefox https://example.com') +``` + + + + Full walkthrough and examples + + +--- + +## Choosing the Right SDK + + + + - Want default Ubuntu VM + - Want to use [MCP-Gateway]() + - Do not need to use code [interpreter specific functions]() + + + + - AI data analysis and visualization + - Multi-language code execution (Python, JavaScript, R, Java, Bash) + - Need data science libraries pre-installed + - Generating charts, plots, or reports + - Jupyter-like code execution environment + + + + - Browser automation with visual feedback + - Testing applications that require a GUI + - Screen recording or screenshots + - Running desktop applications in the cloud + + From e3755b616e0880bfb070fd041d2fb82934960191 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Tue, 13 Jan 2026 17:16:51 +0100 Subject: [PATCH 5/7] Add more pages for poc --- docs.json | 24 +++- docs.mdx | 18 ++- docs/code-interpreter.mdx | 213 +++++++++++++++++++++++++++++++++++ docs/dashboard/billing.mdx | 9 ++ docs/dashboard/templates.mdx | 9 ++ docs/dashboard/usage.mdx | 9 ++ docs/dashboard/webhooks.mdx | 9 ++ docs/desktop/intro.mdx | 118 +++++++++++++++++++ 8 files changed, 398 insertions(+), 11 deletions(-) create mode 100644 docs/code-interpreter.mdx create mode 100644 docs/dashboard/billing.mdx create mode 100644 docs/dashboard/templates.mdx create mode 100644 docs/dashboard/usage.mdx create mode 100644 docs/dashboard/webhooks.mdx create mode 100644 docs/desktop/intro.mdx diff --git a/docs.json b/docs.json index 0d035fa..5a821c2 100644 --- a/docs.json +++ b/docs.json @@ -36,7 +36,8 @@ "docs/quickstart/install-custom-packages" ] }, - "docs/api-key" + "docs/api-key", + "docs/sdks-explained" ] }, { @@ -65,6 +66,27 @@ "docs/templates/intro" ] }, + { + "group": "Code Interpreter", + "pages": [ + "docs/code-interpreter" + ] + }, + { + "group": "Desktop", + "pages": [ + "docs/desktop/intro" + ] + }, + { + "group": "Dashboard", + "pages": [ + "docs/dashboard/billing", + "docs/dashboard/usage", + "docs/dashboard/webhooks", + "docs/dashboard/templates" + ] + }, { "group": "FAQ", "pages": [ diff --git a/docs.mdx b/docs.mdx index 57cbfc9..ec04f59 100644 --- a/docs.mdx +++ b/docs.mdx @@ -6,12 +6,10 @@ icon: house import { Quickstart } from '/snippets/Quickstart.jsx'; import { CodeInterpreting } from '/snippets/CodeInterpreting.jsx'; -import { Examples } from '/snippets/Examples.jsx'; -import { Reference } from '/snippets/Reference.jsx'; ## What is E2B? -E2B provides isolated sandboxes that let agents safely execute code, process data, and run tools. Our [SDKs]() make it easy to start and manage these environments. +E2B provides isolated sandboxes that let agents safely execute code, process data, and run tools. Our [SDKs](/docs/sdks-explained) make it easy to start and manage these environments. ## E2B Building Blocks @@ -31,16 +29,16 @@ The documentation is split into three main sections: - [**API/SDK Reference**](https://e2b.dev/docs/sdk-reference) — A complete technical reference for every feature, component, and configuration option. -
- ## 🚀 Quickstart. -
- ## 🧠 Examples - - -
\ No newline at end of file + + + + + + + diff --git a/docs/code-interpreter.mdx b/docs/code-interpreter.mdx new file mode 100644 index 0000000..db68a6c --- /dev/null +++ b/docs/code-interpreter.mdx @@ -0,0 +1,213 @@ +--- +title: "Code Interpreter" +description: "Multi-language code execution with pre-installed data science libraries, visualization support, and built on top of the core E2B SDK." +icon: "code" +--- + +# Code Interpreter + +Built on top of `e2b` with added support for multi-language code execution (Python, JavaScript, R, Java, Bash), pre-installed data science libraries, and visualization capabilities. + + +Includes **all features from `e2b`** plus specialized code execution methods and pre-configured environment. + + +## Installation + + +```bash Python +pip install e2b-code-interpreter +``` + +```bash JavaScript +npm install @e2b/code-interpreter +``` + + +## Quick Start + + +```python Python +from e2b_code_interpreter import Sandbox + +# Create code interpreter +sbx = Sandbox() + +# Execute Python with visualization +execution = sbx.run_code(""" +import matplotlib.pyplot as plt +plt.plot([1, 2, 3, 4]) +plt.ylabel('some numbers') +plt.savefig('chart.png') +""") + +# Access results +for result in execution.results: + print(result) + +sbx.close() +``` + +```typescript JavaScript +import { Sandbox } from '@e2b/code-interpreter' + +// Create code interpreter +const sbx = await Sandbox.create() + +// Execute Python with visualization +const execution = await sbx.runCode(` +import matplotlib.pyplot as plt +plt.plot([1, 2, 3, 4]) +plt.ylabel('some numbers') +plt.savefig('chart.png') +`) + +// Access results +execution.results.forEach(result => console.log(result)) + +await sbx.close() +``` + + +## Supported Languages + + + + Full Python support with data science libraries + + + Node.js runtime for JavaScript execution + + + Statistical computing with R + + + Java code execution + + + Shell scripts and commands + + + +## Pre-installed Libraries + +The code interpreter comes with popular data science and visualization libraries: + + + + - **Data Analysis:** pandas, numpy, scipy + - **Visualization:** matplotlib, seaborn, plotly + - **Machine Learning:** scikit-learn + - **And many more...** + + [View full list →](/docs/code-interpreting/analyze-data-with-ai/pre-installed-libraries) + + + + - **Node.js built-in modules** + - **Popular npm packages** (install as needed) + + + +## Features + +### Code Execution Results + +Access execution results including stdout, stderr, charts, and data: + + +```python Python +execution = sbx.run_code("print('Hello'); 2 + 2") + +for result in execution.results: + if result.type == "stdout": + print(result.text) + elif result.type == "result": + print(result.data) +``` + +```typescript JavaScript +const execution = await sbx.runCode("console.log('Hello'); 2 + 2") + +execution.results.forEach(result => { + if (result.type === 'stdout') { + console.log(result.text) + } else if (result.type === 'result') { + console.log(result.data) + } +}) +``` + + +### Chart Generation + +Create and retrieve visualizations: + + +```python Python +execution = sbx.run_code(""" +import matplotlib.pyplot as plt +import numpy as np + +x = np.linspace(0, 10, 100) +plt.plot(x, np.sin(x)) +plt.title('Sine Wave') +plt.savefig('plot.png') +""") + +# Charts are available in results +for result in execution.results: + if result.type == "image": + print(f"Chart saved: {result.url}") +``` + +```typescript JavaScript +const execution = await sbx.runCode(` +import matplotlib.pyplot as plt +import numpy as np + +x = np.linspace(0, 10, 100) +plt.plot(x, np.sin(x)) +plt.title('Sine Wave') +plt.savefig('plot.png') +`) + +// Charts are available in results +execution.results.forEach(result => { + if (result.type === 'image') { + console.log(`Chart saved: ${result.url}`) + } +}) +``` + + +## Use Cases + + + + Build AI agents that analyze datasets and create visualizations + + + Create Jupyter-like environments for interactive coding + + + Generate reports with code, analysis, and charts + + + Run student code safely in sandboxed environments + + + +## Related Resources + + + + Full list of available libraries + + + Chart generation guide + + + Complete API documentation + + diff --git a/docs/dashboard/billing.mdx b/docs/dashboard/billing.mdx new file mode 100644 index 0000000..f317ad1 --- /dev/null +++ b/docs/dashboard/billing.mdx @@ -0,0 +1,9 @@ +--- +title: "Billing" +description: "Manage your E2B subscription, view pricing plans, and understand billing for sandbox usage, compute time, and storage." +icon: "credit-card" +--- + +# Billing + +Content coming soon. diff --git a/docs/dashboard/templates.mdx b/docs/dashboard/templates.mdx new file mode 100644 index 0000000..00a55e0 --- /dev/null +++ b/docs/dashboard/templates.mdx @@ -0,0 +1,9 @@ +--- +title: "Templates" +description: "Manage your custom sandbox templates in the E2B dashboard, including creating, editing, and deploying templates for your team." +icon: "layer-group" +--- + +# Templates + +Content coming soon. diff --git a/docs/dashboard/usage.mdx b/docs/dashboard/usage.mdx new file mode 100644 index 0000000..dcdd291 --- /dev/null +++ b/docs/dashboard/usage.mdx @@ -0,0 +1,9 @@ +--- +title: "Usage" +description: "Monitor your E2B usage metrics including active sandboxes, compute hours, API calls, and resource consumption across your projects." +icon: "chart-simple" +--- + +# Usage + +Content coming soon. diff --git a/docs/dashboard/webhooks.mdx b/docs/dashboard/webhooks.mdx new file mode 100644 index 0000000..1c0b72f --- /dev/null +++ b/docs/dashboard/webhooks.mdx @@ -0,0 +1,9 @@ +--- +title: "Webhooks" +description: "Configure webhooks to receive real-time notifications about sandbox events, lifecycle changes, and system updates from E2B." +icon: "webhook" +--- + +# Webhooks + +Content coming soon. diff --git a/docs/desktop/intro.mdx b/docs/desktop/intro.mdx new file mode 100644 index 0000000..33afe6f --- /dev/null +++ b/docs/desktop/intro.mdx @@ -0,0 +1,118 @@ +--- +title: "Desktop Intro" +description: "Full Linux desktop environment with GUI, browser automation, and window management built on top of the E2B SDK." +icon: "desktop" +--- + +# Desktop + +Built on top of `e2b` with a full Linux desktop environment including GUI, browser, and window management capabilities. + + +Includes **all features from `e2b`** plus desktop-specific methods like `getDesktopUrl()` and pre-configured GUI environment. + + +## Installation + + +```bash Python +pip install e2b-desktop +``` + +```bash JavaScript +npm install @e2b/desktop +``` + + +## Quick Start + + +```python Python +from e2b_desktop import Sandbox + +# Create desktop sandbox +sbx = Sandbox.create() + +# Get desktop URL +desktop_url = sbx.get_desktop_url() +print(f"Access desktop at: {desktop_url}") + +# Run GUI application +sbx.commands.run("firefox https://example.com") +``` + +```typescript JavaScript +import { Sandbox } from '@e2b/desktop' + +// Create desktop sandbox +const sbx = await Sandbox.create() + +// Get desktop URL +const desktopUrl = await sbx.getDesktopUrl() +console.log(`Access desktop at: ${desktopUrl}`) + +// Run GUI application +await sbx.commands.run('firefox https://example.com') +``` + + +## Features + +### Remote Desktop Access + +Access a full Linux desktop environment in your browser: + +- **Window Management:** Run multiple applications with full window controls +- **Browser Access:** Remote desktop URL for web-based access +- **Screen Resolution:** Configurable display settings +- **Clipboard Support:** Copy/paste between local and remote environments + +### Pre-installed Applications + +The desktop comes with common applications: + + + + Firefox, Chromium for browser automation + + + Text editors, terminals, and dev utilities + + + Image viewers and basic media players + + + File managers and system monitors + + + +## Use Cases + + + + Automate web interactions with visual feedback + + + Test applications requiring GUI in isolated environments + + + Record application behavior and workflows + + + Cloud-based development with full desktop access + + + +## Related Resources + + + + Complete walkthrough and examples + + + Complete API documentation + + + Customize your desktop environment + + From bdec11a30b50c09545651ba2d5a3c576cb664842 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Fri, 23 Jan 2026 15:49:25 +0100 Subject: [PATCH 6/7] 1st desktop use case --- docs/use-cases/linux-desktop.mdx | 830 ++++++++++++++++++++++++++++++- 1 file changed, 828 insertions(+), 2 deletions(-) diff --git a/docs/use-cases/linux-desktop.mdx b/docs/use-cases/linux-desktop.mdx index 94c9e10..446b2e9 100644 --- a/docs/use-cases/linux-desktop.mdx +++ b/docs/use-cases/linux-desktop.mdx @@ -4,6 +4,832 @@ description: "Run full Linux desktop environments in E2B sandboxes with GUI supp icon: "desktop" --- -# Linux Desktop +## Setup Project -Content coming soon. + + + + ```bash Bash + npx create-next-app@latest surf-starter --typescript --app --no-tailwind + cd surf-starter + ``` + + + + + + ```bash Bash + npm install @e2b/desktop openai sharp + ``` + + + + + + ```env Environment + # .env + E2B_API_KEY=your_e2b_api_key + OPENAI_API_KEY=your_openai_api_key + ``` + + + + +## Type Definitions + + + + + ```ts JavaScript & TypeScript + // types/index.ts + export interface ChatMessage { + role: 'user' | 'assistant' | 'system' | 'action'; + content: string; + } + + export type ComputerAction = + | { type: 'click'; x: number; y: number; button: 'left' | 'right' | 'wheel' } + | { type: 'double_click'; x: number; y: number } + | { type: 'type'; text: string } + | { type: 'key' | 'keypress'; keys?: string[]; key?: string } + | { type: 'move'; x: number; y: number } + | { type: 'drag'; start_x: number; start_y: number; x: number; y: number } + | { type: 'scroll'; amount: number } + | { type: 'wait'; duration?: number } + | { type: 'screenshot' }; + + export interface SSEEvent { + type: 'sandbox_created' | 'reasoning' | 'action' | 'action_completed' | 'done' | 'error'; + content?: string; + action?: string; + sandboxId?: string; + url?: string; + message?: string; + } + ``` + + + + +## Configuration + + + + + ```ts JavaScript & TypeScript + // lib/constants.ts + export const SANDBOX_CONFIG = { + TIMEOUT_MS: 300_000, + TIMEOUT_SECONDS: 300, + AUTO_EXTEND_THRESHOLD: 10, + } as const; + + export const SCREENSHOT_CONFIG = { + MAX_WIDTH: 1024, + MAX_HEIGHT: 768, + } as const; + + export const AI_CONFIG = { + MODEL: 'computer-use-preview', + MAX_ITERATIONS: 15, + MAX_WAIT_DURATION: 3000, + REASONING_EFFORT: 'medium', + } as const; + ``` + + + + + + ```ts JavaScript & TypeScript + // lib/env.ts + export function getEnv() { + const E2B_API_KEY = process.env.E2B_API_KEY; + const OPENAI_API_KEY = process.env.OPENAI_API_KEY; + + if (!E2B_API_KEY || !OPENAI_API_KEY) { + throw new Error('Missing required environment variables'); + } + + return { E2B_API_KEY, OPENAI_API_KEY }; + } + + export function isEnvironmentConfigured(): boolean { + return !!(process.env.E2B_API_KEY && process.env.OPENAI_API_KEY); + } + ``` + + + + +## Utilities + + + + + ```ts JavaScript & TypeScript + // lib/utils/screenshot.ts + import sharp from 'sharp'; + import { SCREENSHOT_CONFIG } from '@/lib/constants'; + + export async function processScreenshot( + screenshotBuffer: Uint8Array | Buffer + ): Promise { + const processedBuffer = await sharp(screenshotBuffer) + .resize(SCREENSHOT_CONFIG.MAX_WIDTH, SCREENSHOT_CONFIG.MAX_HEIGHT, { + fit: 'contain', + background: { r: 0, g: 0, b: 0, alpha: 1 }, + }) + .png() + .toBuffer(); + + return processedBuffer.toString('base64'); + } + ``` + + + + + + ```ts JavaScript & TypeScript + // lib/utils/stream.ts + export function createSafeStreamController( + controller: ReadableStreamDefaultController + ) { + let isControllerClosed = false; + + const safeEnqueue = (data: Uint8Array): void => { + if (!isControllerClosed) { + try { + controller.enqueue(data); + } catch (error) { + isControllerClosed = true; + } + } + }; + + const safeClose = (): void => { + if (!isControllerClosed) { + try { + controller.close(); + isControllerClosed = true; + } catch (error) { + isControllerClosed = true; + } + } + }; + + return { enqueue: safeEnqueue, close: safeClose }; + } + + export function createSSEEvent(event: object): string { + return `data: ${JSON.stringify(event)}\n\n`; + } + ``` + + + + + + ```ts JavaScript & TypeScript + // lib/utils/actions.ts + import type { Sandbox } from '@e2b/desktop'; + import type { ComputerAction } from '@/types'; + + export async function executeComputerAction( + sandbox: Sandbox, + action: ComputerAction + ): Promise { + switch (action.type) { + case 'click': + if (action.button === 'left') { + await sandbox.leftClick(action.x, action.y); + } else if (action.button === 'right') { + await sandbox.rightClick(action.x, action.y); + } + break; + + case 'double_click': + await sandbox.doubleClick(action.x, action.y); + break; + + case 'type': + await sandbox.write(action.text); + break; + + case 'key': + case 'keypress': + const key = action.keys?.[0] || action.key; + if (key) await sandbox.press(key); + break; + + case 'move': + await sandbox.moveMouse(action.x, action.y); + break; + + case 'scroll': + await sandbox.scroll(action.amount < 0 ? 'up' : 'down'); + break; + + case 'wait': + await new Promise(resolve => + setTimeout(resolve, Math.min(action.duration || 1000, 3000)) + ); + break; + } + } + + export function formatActionForDisplay(action: ComputerAction): string { + switch (action.type) { + case 'click': + return `Click ${action.button} at (${action.x}, ${action.y})`; + case 'type': + return `Type: "${action.text}"`; + case 'key': + case 'keypress': + return `Press key: ${action.keys?.[0] || action.key}`; + default: + return `Action: ${action.type}`; + } + } + ``` + + + + +## AI Instructions + + + + + ```ts JavaScript & TypeScript + // lib/ai/instructions.ts + export const SYSTEM_INSTRUCTIONS = `You are Surf, a helpful AI assistant that can control a computer. + +ENVIRONMENT: +- Ubuntu 22.04 Linux desktop sandbox +- Pre-installed: Firefox, VS Code, Terminal, File Manager +- Desktop is READY - start immediately + +AVAILABLE ACTIONS: +- click: Click at coordinates (left/right/middle) +- double_click: Double-click at coordinates +- type: Type text +- key/keypress: Press keyboard keys (ENTER, ESC, TAB) +- move: Move cursor without clicking +- drag: Drag from one position to another +- scroll: Scroll up or down +- wait: Wait briefly (max 3 seconds) + +RULES: +- Be AUTONOMOUS - execute without asking permission +- When user says "yes" or "proceed" - take action immediately +- Press ENTER after typing terminal commands +- Never wait at start - desktop is ready +- Only wait after opening apps (1-2 seconds max) + +REMEMBER: Execute tasks directly without asking "Should I proceed?"`; + ``` + + + + +## OpenAI Service + + + + + ```ts JavaScript & TypeScript + // lib/services/openai.ts + import OpenAI from 'openai'; + import type { Sandbox } from '@e2b/desktop'; + import { AI_CONFIG, SCREENSHOT_CONFIG } from '@/lib/constants'; + import { SYSTEM_INSTRUCTIONS } from '@/lib/ai/instructions'; + import { processScreenshot } from '@/lib/utils/screenshot'; + import { executeComputerAction, formatActionForDisplay } from '@/lib/utils/actions'; + import { getEnv } from '@/lib/env'; + + export async function runComputerUseLoop( + sandbox: Sandbox, + userMessage: string, + sendEvent: (data: Uint8Array) => void + ): Promise { + const { OPENAI_API_KEY } = getEnv(); + const openai = new OpenAI({ apiKey: OPENAI_API_KEY }); + const encoder = new TextEncoder(); + + // Take initial screenshot + const screenshotBuffer = await sandbox.screenshot(); + const screenshotBase64 = await processScreenshot(screenshotBuffer); + + // Define computer tool + const computerTool = { + type: 'computer-preview' as const, + display_width: SCREENSHOT_CONFIG.MAX_WIDTH, + display_height: SCREENSHOT_CONFIG.MAX_HEIGHT, + environment: 'linux' as const, + }; + + // Create initial request + let response = await openai.responses.create({ + model: AI_CONFIG.MODEL, + tools: [computerTool], + input: [{ + type: 'message', + role: 'user', + content: [ + { type: 'input_text', text: userMessage }, + { type: 'input_image', image_url: `data:image/png;base64,${screenshotBase64}`, detail: 'high' }, + ], + }], + instructions: SYSTEM_INSTRUCTIONS, + truncation: 'auto', + reasoning: { effort: AI_CONFIG.REASONING_EFFORT, generate_summary: 'concise' }, + }); + + let iterations = 0; + + // Main loop + while (iterations < AI_CONFIG.MAX_ITERATIONS) { + iterations++; + + const computerCalls = response.output.filter( + (item: any) => item.type === 'computer_call' + ); + + if (computerCalls.length === 0) { + sendEvent(encoder.encode(`data: ${JSON.stringify({ + type: 'reasoning', + content: response.output_text || 'Task complete!' + })}\n\n`)); + break; + } + + const computerCall = computerCalls[0]; + const action = computerCall.action; + + // Send action to client + sendEvent(encoder.encode(`data: ${JSON.stringify({ + type: 'action', + action: formatActionForDisplay(action) + })}\n\n`)); + + // Execute action + await executeComputerAction(sandbox, action); + + sendEvent(encoder.encode(`data: ${JSON.stringify({ + type: 'action_completed' + })}\n\n`)); + + // Take new screenshot + const newScreenshotBuffer = await sandbox.screenshot(); + const newScreenshotBase64 = await processScreenshot(newScreenshotBuffer); + + // Continue conversation + response = await openai.responses.create({ + model: AI_CONFIG.MODEL, + previous_response_id: response.id, + instructions: SYSTEM_INSTRUCTIONS, + tools: [computerTool], + input: [{ + call_id: computerCall.call_id, + type: 'computer_call_output', + output: { + type: 'computer_screenshot', + image_url: `data:image/png;base64,${newScreenshotBase64}`, + }, + }], + truncation: 'auto', + reasoning: { effort: AI_CONFIG.REASONING_EFFORT, generate_summary: 'concise' }, + }); + } + } + ``` + + + + +## API Route + + + + + ```ts JavaScript & TypeScript + // app/api/chat/route.ts + import { Sandbox } from '@e2b/desktop'; + import { NextRequest } from 'next/server'; + import { getEnv, isEnvironmentConfigured } from '@/lib/env'; + import { SANDBOX_CONFIG } from '@/lib/constants'; + import { createSafeStreamController, createSSEEvent } from '@/lib/utils/stream'; + import { runComputerUseLoop } from '@/lib/services/openai'; + + const sandboxes = new Map(); + + export async function POST(req: NextRequest) { + try { + const { message, sandboxId } = await req.json(); + + if (!message) { + return new Response(JSON.stringify({ error: 'Message required' }), { status: 400 }); + } + + if (!isEnvironmentConfigured()) { + return new Response(createSSEEvent({ type: 'error', message: 'Missing API keys' }), { + headers: { 'Content-Type': 'text/event-stream' }, + }); + } + + const { E2B_API_KEY } = getEnv(); + const encoder = new TextEncoder(); + + const stream = new ReadableStream({ + async start(controller) { + const safeController = createSafeStreamController(controller); + + try { + let sandbox = sandboxId ? sandboxes.get(sandboxId) : null; + + if (!sandbox) { + safeController.enqueue(encoder.encode(createSSEEvent({ + type: 'reasoning', + content: 'Creating sandbox...', + }))); + + sandbox = await Sandbox.create({ + apiKey: E2B_API_KEY, + timeoutMs: SANDBOX_CONFIG.TIMEOUT_MS, + }); + + await sandbox.stream.start(); + sandboxes.set(sandbox.sandboxId, sandbox); + + safeController.enqueue(encoder.encode(createSSEEvent({ + type: 'sandbox_created', + sandboxId: sandbox.sandboxId, + url: sandbox.stream.getUrl(), + }))); + } else { + await sandbox.setTimeout(SANDBOX_CONFIG.TIMEOUT_MS); + } + + await runComputerUseLoop(sandbox, message, safeController.enqueue); + + safeController.enqueue(encoder.encode(createSSEEvent({ type: 'done' }))); + safeController.close(); + } catch (error) { + safeController.enqueue(encoder.encode(createSSEEvent({ + type: 'error', + message: error instanceof Error ? error.message : 'Unknown error', + }))); + safeController.close(); + } + }, + }); + + return new Response(stream, { + headers: { + 'Content-Type': 'text/event-stream', + 'Cache-Control': 'no-cache', + 'Connection': 'keep-alive', + }, + }); + } catch (error) { + return new Response( + JSON.stringify({ error: error instanceof Error ? error.message : 'Internal error' }), + { status: 500 } + ); + } + } + + export const runtime = 'nodejs'; + export const maxDuration = 300; + ``` + + + + + + ```ts JavaScript & TypeScript + // app/actions.ts + 'use server'; + + import { Sandbox } from '@e2b/desktop'; + import { getEnv } from '@/lib/env'; + import { SANDBOX_CONFIG } from '@/lib/constants'; + + export async function extendSandboxTimeout(sandboxId: string) { + try { + if (!sandboxId) { + return { success: false, error: 'Sandbox ID required' }; + } + + const { E2B_API_KEY } = getEnv(); + const sandbox = await Sandbox.connect(sandboxId, { apiKey: E2B_API_KEY }); + await sandbox.setTimeout(SANDBOX_CONFIG.TIMEOUT_MS); + + return { success: true }; + } catch (error) { + return { + success: false, + error: error instanceof Error ? error.message : 'Unknown error', + }; + } + } + + export async function stopSandbox(sandboxId: string) { + try { + if (!sandboxId) { + return { success: false, error: 'Sandbox ID required' }; + } + + const { E2B_API_KEY } = getEnv(); + const sandbox = await Sandbox.connect(sandboxId, { apiKey: E2B_API_KEY }); + await sandbox.kill(); + + return { success: true }; + } catch (error) { + return { + success: false, + error: error instanceof Error ? error.message : 'Unknown error', + }; + } + } + ``` + + + + +## Frontend + + + + + ```tsx TypeScript + // app/page.tsx + 'use client'; + + import { useState, useRef, useEffect } from 'react'; + import { extendSandboxTimeout, stopSandbox } from './actions'; + import { SANDBOX_CONFIG } from '@/lib/constants'; + import type { ChatMessage } from '@/types'; + + export default function Home() { + const [messages, setMessages] = useState([]); + const [input, setInput] = useState(''); + const [loading, setLoading] = useState(false); + const [sandboxUrl, setSandboxUrl] = useState(''); + const [sandboxId, setSandboxId] = useState(''); + const [timeRemaining, setTimeRemaining] = useState(SANDBOX_CONFIG.TIMEOUT_SECONDS); + + const sendMessage = async (e: React.FormEvent) => { + e.preventDefault(); + if (!input.trim() || loading) return; + + setMessages(prev => [...prev, { role: 'user', content: input }]); + setInput(''); + setLoading(true); + + try { + const response = await fetch('/api/chat', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ message: input, sandboxId: sandboxId || undefined }), + }); + + const reader = response.body?.getReader(); + const decoder = new TextDecoder(); + let buffer = ''; + + while (true) { + const { done, value } = await reader!.read(); + if (done) break; + + buffer += decoder.decode(value, { stream: true }); + const lines = buffer.split('\n'); + buffer = lines.pop() || ''; + + for (const line of lines) { + if (line.startsWith('data: ')) { + const data = line.slice(6); + if (data === '[DONE]') continue; + + const parsed = JSON.parse(data); + + if (parsed.type === 'sandbox_created') { + setSandboxId(parsed.sandboxId); + setSandboxUrl(parsed.url); + } else if (parsed.type === 'reasoning') { + setMessages(prev => { + const last = prev[prev.length - 1]; + if (last?.role === 'assistant') { + return [...prev.slice(0, -1), { role: 'assistant', content: parsed.content }]; + } + return [...prev, { role: 'assistant', content: parsed.content }]; + }); + } else if (parsed.type === 'action') { + setMessages(prev => [...prev, { role: 'action', content: parsed.action }]); + } + } + } + } + } catch (error) { + console.error('Error:', error); + } finally { + setLoading(false); + } + }; + + return ( +
+
+

🏄 Surf Demo

+

AI agent with E2B desktop sandbox

+
+ +
+
+ {sandboxUrl ? ( +