From 84d786274429554976744f7bde0e6df7217a09c3 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Thu, 29 Jan 2026 18:45:46 +0100 Subject: [PATCH 1/4] feat: add sandbox overview page - Create new sandbox overview page as the entry point for the Sandbox section - Move lifecycle content (timeout, shutdown, get info) to dedicated lifecycle page - Update navigation to include new lifecycle page - Update Concepts component with sandbox overview and lifecycle cards - Verify and correct default configuration values (2 vCPUs, 2 GiB RAM, 22 GiB storage) - Fix startup time to ~100ms Co-Authored-By: Claude Opus 4.5 --- docs.json | 1 + docs/sandbox.mdx | 184 ++++++++++++------------------------- docs/sandbox/lifecycle.mdx | 141 ++++++++++++++++++++++++++++ snippets/Concepts.jsx | 9 +- 4 files changed, 208 insertions(+), 127 deletions(-) create mode 100644 docs/sandbox/lifecycle.mdx diff --git a/docs.json b/docs.json index 13fe53d..05c764a 100644 --- a/docs.json +++ b/docs.json @@ -79,6 +79,7 @@ "group": "Sandbox", "pages": [ "docs/sandbox", + "docs/sandbox/lifecycle", "docs/sandbox/lifecycle-events-api", "docs/sandbox/lifecycle-events-webhooks", "docs/sandbox/persistence", diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx index e075402..ab1144c 100644 --- a/docs/sandbox.mdx +++ b/docs/sandbox.mdx @@ -1,141 +1,73 @@ --- -title: "Sandbox lifecycle" -sidebarTitle: Lifecycle +title: "Sandbox overview" +sidebarTitle: Overview +description: "Isolated cloud environments for running AI-generated code" --- -When you start the sandbox, it stays alive for 5 minutes by default but you can change it by passing the `timeout` parameter. -After the time passes, the sandbox will be automatically shutdown. - - -The maximum time sandbox can be kept running without being paused is -- 24 hours on the Pro Tier -- 1 hour on the Base Tier - -For more details, please refer to [sandbox persistance page](/docs/sandbox/persistence#limitations-while-in-beta). - - - -```js JavaScript & TypeScript highlight={6} -import { Sandbox } from '@e2b/code-interpreter' - -// Create sandbox with and keep it running for 60 seconds. -// 🚨 Note: The units are milliseconds. -const sandbox = await Sandbox.create({ - timeoutMs: 60_000, -}) -``` -```python Python highlight={6} -from e2b_code_interpreter import Sandbox - -# Create sandbox with and keep it running for 60 seconds. -# 🚨 Note: The units are seconds. -sandbox = Sandbox.create( - timeout=60, -) -``` - - - -## Change sandbox timeout during runtime - -You can change the sandbox timeout when it's running by calling the `setTimeout` method in JavaScript or `set_timeout` method in Python. - -When you call the set timeout method, the sandbox timeout will be reset to the new value that you specified. - -This can be useful if you want to extend the sandbox lifetime when it's already running. -You can for example start with a sandbox with 1 minute timeout and then periodically call set timeout every time user interacts with it in your app. - - -```js JavaScript & TypeScript -import { Sandbox } from '@e2b/code-interpreter' - -// Create sandbox with and keep it running for 60 seconds. -const sandbox = await Sandbox.create({ timeoutMs: 60_000 }) - -// Change the sandbox timeout to 30 seconds. -// 🚨 The new timeout will be 30 seconds from now. -await sandbox.setTimeout(30_000) -``` -```python Python -from e2b_code_interpreter import Sandbox - -# Create sandbox with and keep it running for 60 seconds. -sandbox = Sandbox.create(timeout=60) - -# Change the sandbox timeout to 30 seconds. -# 🚨 The new timeout will be 30 seconds from now. -sandbox.set_timeout(30) -``` - - -## Retrieve sandbox information - -You can retrieve sandbox information like sandbox ID, template, metadata, started at/end at date by calling the `getInfo` method in JavaScript or `get_info` method in Python. +A sandbox is an isolated cloud VM that starts in **~100ms**. Each sandbox has its own filesystem, can run processes, and has internet access. Sandboxes are designed to run AI-generated code safely. ```js JavaScript & TypeScript import { Sandbox } from '@e2b/code-interpreter' -// Create sandbox with and keep it running for 60 seconds. -const sandbox = await Sandbox.create({ timeoutMs: 60_000 }) - -// Retrieve sandbox information. -const info = await sandbox.getInfo() - -console.log(info) - -// { -// "sandboxId": "iiny0783cype8gmoawzmx-ce30bc46", -// "templateId": "rki5dems9wqfm4r03t7g", -// "name": "base", -// "metadata": {}, -// "startedAt": "2025-03-24T15:37:58.076Z", -// "endAt": "2025-03-24T15:42:58.076Z" -// } +const sbx = await Sandbox.create() +const result = await sbx.runCode('print(1 + 1)') +console.log(result.text) // 2 +await sbx.kill() ``` - ```python Python from e2b_code_interpreter import Sandbox -# Create sandbox with and keep it running for 60 seconds. -sandbox = Sandbox.create(timeout=60) - -# Retrieve sandbox information. -info = sandbox.get_info() - -print(info) - -# SandboxInfo(sandbox_id='ig6f1yt6idvxkxl562scj-419ff533', -# template_id='u7nqkmpn3jjf1tvftlsu', -# name='base', -# metadata={}, -# started_at=datetime.datetime(2025, 3, 24, 15, 42, 59, 255612, tzinfo=tzutc()), -# end_at=datetime.datetime(2025, 3, 24, 15, 47, 59, 255612, tzinfo=tzutc()) -# ) +sbx = Sandbox() +result = sbx.run_code('print(1 + 1)') +print(result.text) # 2 +sbx.kill() ``` -## Shutdown sandbox - -You can shutdown the sandbox any time even before the timeout is up by calling the `kill` method. - - -```js JavaScript & TypeScript -import { Sandbox } from '@e2b/code-interpreter' - -// Create sandbox with and keep it running for 60 seconds. -const sandbox = await Sandbox.create({ timeoutMs: 60_000 }) - -// Shutdown the sandbox immediately. -await sandbox.kill() -``` -```python Python -from e2b_code_interpreter import Sandbox - -# Create sandbox with and keep it running for 60 seconds. -sandbox = Sandbox.create(timeout=60) - -# Shutdown the sandbox immediately. -sandbox.kill() -``` - +## Key features + + + + Read, write, upload, and download files + + + Run shell commands and start processes + + + Manage timeout, get info, and shutdown + + + Pause and resume sandboxes with full state + + + +## Default configuration + +| Property | Value | +|----------|-------| +| vCPUs | 2 | +| RAM | 2 GiB | +| Storage | 22 GiB | +| Internet | Enabled | + + +These are defaults for the [code-interpreter](https://github.com/e2b-dev/code-interpreter) template. Custom templates can have different CPU/RAM configurations. + + +See [lifecycle](/docs/sandbox/lifecycle) for timeout configuration. + +## Sandbox capabilities + +| Capability | Description | +|------------|-------------| +| [Run code](/docs/code-interpreting/analyze-data-with-ai) | Execute Python, JavaScript, R, Java, Bash | +| [Filesystem](/docs/filesystem) | Full read/write access to isolated filesystem | +| [Commands](/docs/commands) | Run any shell command or process | +| [Internet](/docs/sandbox/internet-access) | Outbound HTTP/HTTPS requests | +| [Persistence](/docs/sandbox/persistence) | Pause/resume with full memory state | +| [Metadata](/docs/sandbox/metadata) | Attach custom key-value data | +| [Environment variables](/docs/sandbox/environment-variables) | Pass secrets and configuration | +| [Webhooks](/docs/sandbox/lifecycle-events-webhooks) | Get notified on lifecycle events | + +For pricing details, see [Billing](/docs/billing). diff --git a/docs/sandbox/lifecycle.mdx b/docs/sandbox/lifecycle.mdx new file mode 100644 index 0000000..78792d0 --- /dev/null +++ b/docs/sandbox/lifecycle.mdx @@ -0,0 +1,141 @@ +--- +title: "Sandbox lifecycle" +sidebarTitle: Lifecycle +--- + +When you start the sandbox, it stays alive for 5 minutes by default but you can change it by passing the `timeout` parameter. +After the time passes, the sandbox will be automatically shutdown. + + +The maximum time sandbox can be kept running without being paused is +- 24 hours on the Pro Tier +- 1 hour on the Base Tier + +For more details, please refer to [sandbox persistance page](/docs/sandbox/persistence#limitations-while-in-beta). + + + +```js JavaScript & TypeScript highlight={6} +import { Sandbox } from '@e2b/code-interpreter' + +// Create sandbox with and keep it running for 60 seconds. +// 🚨 Note: The units are milliseconds. +const sandbox = await Sandbox.create({ + timeoutMs: 60_000, +}) +``` +```python Python highlight={6} +from e2b_code_interpreter import Sandbox + +# Create sandbox with and keep it running for 60 seconds. +# 🚨 Note: The units are seconds. +sandbox = Sandbox.create( + timeout=60, +) +``` + + + +## Change sandbox timeout during runtime + +You can change the sandbox timeout when it's running by calling the `setTimeout` method in JavaScript or `set_timeout` method in Python. + +When you call the set timeout method, the sandbox timeout will be reset to the new value that you specified. + +This can be useful if you want to extend the sandbox lifetime when it's already running. +You can for example start with a sandbox with 1 minute timeout and then periodically call set timeout every time user interacts with it in your app. + + +```js JavaScript & TypeScript +import { Sandbox } from '@e2b/code-interpreter' + +// Create sandbox with and keep it running for 60 seconds. +const sandbox = await Sandbox.create({ timeoutMs: 60_000 }) + +// Change the sandbox timeout to 30 seconds. +// 🚨 The new timeout will be 30 seconds from now. +await sandbox.setTimeout(30_000) +``` +```python Python +from e2b_code_interpreter import Sandbox + +# Create sandbox with and keep it running for 60 seconds. +sandbox = Sandbox.create(timeout=60) + +# Change the sandbox timeout to 30 seconds. +# 🚨 The new timeout will be 30 seconds from now. +sandbox.set_timeout(30) +``` + + +## Retrieve sandbox information + +You can retrieve sandbox information like sandbox ID, template, metadata, started at/end at date by calling the `getInfo` method in JavaScript or `get_info` method in Python. + + +```js JavaScript & TypeScript +import { Sandbox } from '@e2b/code-interpreter' + +// Create sandbox with and keep it running for 60 seconds. +const sandbox = await Sandbox.create({ timeoutMs: 60_000 }) + +// Retrieve sandbox information. +const info = await sandbox.getInfo() + +console.log(info) + +// { +// "sandboxId": "iiny0783cype8gmoawzmx-ce30bc46", +// "templateId": "rki5dems9wqfm4r03t7g", +// "name": "base", +// "metadata": {}, +// "startedAt": "2025-03-24T15:37:58.076Z", +// "endAt": "2025-03-24T15:42:58.076Z" +// } +``` + +```python Python +from e2b_code_interpreter import Sandbox + +# Create sandbox with and keep it running for 60 seconds. +sandbox = Sandbox.create(timeout=60) + +# Retrieve sandbox information. +info = sandbox.get_info() + +print(info) + +# SandboxInfo(sandbox_id='ig6f1yt6idvxkxl562scj-419ff533', +# template_id='u7nqkmpn3jjf1tvftlsu', +# name='base', +# metadata={}, +# started_at=datetime.datetime(2025, 3, 24, 15, 42, 59, 255612, tzinfo=tzutc()), +# end_at=datetime.datetime(2025, 3, 24, 15, 47, 59, 255612, tzinfo=tzutc()) +# ) +``` + + +## Shutdown sandbox + +You can shutdown the sandbox any time even before the timeout is up by calling the `kill` method. + + +```js JavaScript & TypeScript +import { Sandbox } from '@e2b/code-interpreter' + +// Create sandbox with and keep it running for 60 seconds. +const sandbox = await Sandbox.create({ timeoutMs: 60_000 }) + +// Shutdown the sandbox immediately. +await sandbox.kill() +``` +```python Python +from e2b_code_interpreter import Sandbox + +# Create sandbox with and keep it running for 60 seconds. +sandbox = Sandbox.create(timeout=60) + +# Shutdown the sandbox immediately. +sandbox.kill() +``` + diff --git a/snippets/Concepts.jsx b/snippets/Concepts.jsx index 6ae8121..c7f1fc2 100644 --- a/snippets/Concepts.jsx +++ b/snippets/Concepts.jsx @@ -2,9 +2,16 @@ export const Concepts = () => { const concepts = [ { href: "/docs/sandbox", + title: "Sandbox overview", + description: + "Learn about sandboxes - isolated cloud VMs for running AI-generated code.", + icon: "box", + }, + { + href: "/docs/sandbox/lifecycle", title: "Sandbox lifecycle", description: - "Learn about how to start the sandbox, manage its lifecycle, and interact with it.", + "Manage sandbox timeout, retrieve info, and shutdown.", icon: "hourglass", }, { From 2804eb24aae9baca272687a8316f3edf14172f6e Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Thu, 29 Jan 2026 19:18:27 +0100 Subject: [PATCH 2/4] fix: revert Concepts.jsx to 4 items for home page layout Keep cards inline in sandbox overview page instead of modifying shared component. Co-Authored-By: Claude Opus 4.5 --- snippets/Concepts.jsx | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/snippets/Concepts.jsx b/snippets/Concepts.jsx index c7f1fc2..9265bd5 100644 --- a/snippets/Concepts.jsx +++ b/snippets/Concepts.jsx @@ -2,18 +2,11 @@ export const Concepts = () => { const concepts = [ { href: "/docs/sandbox", - title: "Sandbox overview", + title: "Sandbox", description: "Learn about sandboxes - isolated cloud VMs for running AI-generated code.", icon: "box", }, - { - href: "/docs/sandbox/lifecycle", - title: "Sandbox lifecycle", - description: - "Manage sandbox timeout, retrieve info, and shutdown.", - icon: "hourglass", - }, { href: "/docs/sandbox/persistence", title: "Sandbox persistence", From a82b0ee794c146e857fb849d7ccf1084f5b76098 Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Thu, 29 Jan 2026 19:25:57 +0100 Subject: [PATCH 3/4] fix: correct code example in sandbox overview - Use Sandbox.create() instead of Sandbox() in Python - Use expression '1 + 1' instead of print() to match result.text usage Co-Authored-By: Claude Opus 4.5 --- docs/sandbox.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx index ab1144c..b7d3709 100644 --- a/docs/sandbox.mdx +++ b/docs/sandbox.mdx @@ -11,15 +11,15 @@ A sandbox is an isolated cloud VM that starts in **~100ms**. Each sandbox has it import { Sandbox } from '@e2b/code-interpreter' const sbx = await Sandbox.create() -const result = await sbx.runCode('print(1 + 1)') +const result = await sbx.runCode('1 + 1') console.log(result.text) // 2 await sbx.kill() ``` ```python Python from e2b_code_interpreter import Sandbox -sbx = Sandbox() -result = sbx.run_code('print(1 + 1)') +sbx = Sandbox.create() +result = sbx.run_code('1 + 1') print(result.text) # 2 sbx.kill() ``` From bac5f532147af5c9e9f536f6dee8bb0329470b9e Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Fri, 30 Jan 2026 22:27:13 +0100 Subject: [PATCH 4/4] fix: address PR feedback - Update intro text with links to filesystem, commands, and firewall - Add link to custom templates in Note section - Change description to "Secure runtime environments for AI agents" --- docs/sandbox.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx index b7d3709..bafc5a9 100644 --- a/docs/sandbox.mdx +++ b/docs/sandbox.mdx @@ -1,10 +1,12 @@ --- title: "Sandbox overview" sidebarTitle: Overview -description: "Isolated cloud environments for running AI-generated code" +description: "Secure runtime environments for AI agents" --- -A sandbox is an isolated cloud VM that starts in **~100ms**. Each sandbox has its own filesystem, can run processes, and has internet access. Sandboxes are designed to run AI-generated code safely. +A sandbox is an agentic runtime which is an isolated cloud VM under the hood. Sandboxes can start in as little as **~100ms**. Each sandbox has its own [filesystem](/docs/filesystem), can start [processes](/docs/commands), and has internet access with [configurable firewall](/docs/sandbox/internet-access#fine-grained-network-control). + +Sandboxes are designed to run thousands of AI agents safely with access to the real-world tools as on your own computer. ```js JavaScript & TypeScript @@ -52,7 +54,7 @@ sbx.kill() | Internet | Enabled | -These are defaults for the [code-interpreter](https://github.com/e2b-dev/code-interpreter) template. Custom templates can have different CPU/RAM configurations. +These are defaults for the [code-interpreter](https://github.com/e2b-dev/code-interpreter) template. [Custom templates](/docs/template/quickstart) can have different CPU/RAM configurations. See [lifecycle](/docs/sandbox/lifecycle) for timeout configuration.