Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

Updated docs on Sandbox.list v2 (#681)

Mish Ushakovc8d338cf4517
diff --git a/apps/web/src/app/(docs)/docs/cli/page.mdx b/apps/web/src/app/(docs)/docs/cli/page.mdx
index ff9ec7aa8..ec1bc9818 100644
--- a/apps/web/src/app/(docs)/docs/cli/page.mdx
+++ b/apps/web/src/app/(docs)/docs/cli/page.mdx
@@ -11,3 +11,13 @@ You can install E2B CLI using the following command:
npm i -g @e2b/cli
```
</CodeGroup>
+
+### Beta CLI
+
+The latest beta version of the CLI can be installed using the following command:
+
+<CodeGroup isTerminalCommand>
+```bash
+npm i -g @e2b/cli@beta
+```
+</CodeGroup>
\ No newline at end of file
diff --git a/apps/web/src/app/(docs)/docs/sandbox/connect/page.mdx b/apps/web/src/app/(docs)/docs/sandbox/connect/page.mdx
index 63d54e0f0..a9b180afc 100644
--- a/apps/web/src/app/(docs)/docs/sandbox/connect/page.mdx
+++ b/apps/web/src/app/(docs)/docs/sandbox/connect/page.mdx
@@ -7,6 +7,10 @@ This is useful if you want to, for example, reuse the same sandbox instance for
## 1. Get the sandbox ID
To connect to a running sandbox, you first need to retrieve its ID. You can do this by calling the `Sandbox.list()` method.
+<Note>
+If you're using the [beta version of the SDKs](/docs/sandbox/installing-beta-sdks), the `Sandbox.list()` method was updated. See [List Sandboxes](/docs/sandbox/list#changes-in-the-beta-sdks) for more information.
+</Note>
+
<CodeGroup>
```js
import { Sandbox } from "@e2b/code-interpreter"
diff --git a/apps/web/src/app/(docs)/docs/sandbox/installing-beta-sdks/page.mdx b/apps/web/src/app/(docs)/docs/sandbox/installing-beta-sdks/page.mdx
new file mode 100644
index 000000000..d05756ec0
--- /dev/null
+++ b/apps/web/src/app/(docs)/docs/sandbox/installing-beta-sdks/page.mdx
@@ -0,0 +1,39 @@
+# Installing beta SDKs
+
+To use features like [sandbox persistence](/docs/sandbox/persistence) and [metrics](/docs/sandbox/metrics), you need to install the beta version of the SDKs.
+
+### Code Interpreter SDK
+
+<CodeGroup>
+```bash {{ language: 'js' }}
+npm i @e2b/code-interpreter@beta
+```
+
+```bash {{ language: 'python' }}
+pip install e2b-code-interpreter==1.2.0b4
+```
+</CodeGroup>
+
+### Core SDK
+
+<CodeGroup>
+```bash {{ language: 'js' }}
+npm i e2b@beta
+```
+
+```bash {{ language: 'python' }}
+pip install e2b==1.2.0b4
+```
+</CodeGroup>
+
+### Desktop SDK
+
+<CodeGroup>
+```bash {{ language: 'js' }}
+npm i @e2b/desktop@beta
+```
+
+```bash {{ language: 'python' }}
+pip install e2b-desktop==1.2.0b1
+```
+</CodeGroup>
\ No newline at end of file
diff --git a/apps/web/src/app/(docs)/docs/sandbox/list/page.mdx b/apps/web/src/app/(docs)/docs/sandbox/list/page.mdx
index b75205530..64ef162d5 100644
--- a/apps/web/src/app/(docs)/docs/sandbox/list/page.mdx
+++ b/apps/web/src/app/(docs)/docs/sandbox/list/page.mdx
@@ -1,8 +1,8 @@
import Link from 'next/link'
-# List running sandboxes
+# List sandboxes
-You can list all running sandboxes using the `Sandbox.list()` method.
+You can list sandboxes using the `Sandbox.list()` method.
<Note>
Once you have information about running sandbox, you can [connect](/docs/sandbox/connect) to it using the `Sandbox.connect()` method.
@@ -12,14 +12,17 @@ Once you have information about running sandbox, you can [connect](/docs/sandbox
```js
import { Sandbox } from '@e2b/code-interpreter'
+// Create a sandbox.
const sandbox = await Sandbox.create({
metadata: {
name: 'My Sandbox',
},
})
+// List all running sandboxes.
const runningSandboxes = await Sandbox.list() // $HighlightLine
const runningSandbox = runningSandboxes[0]
+
console.log('Running sandbox metadata:', runningSandbox.metadata)
console.log('Running sandbox id:', runningSandbox.sandboxId)
console.log('Running sandbox started at:', runningSandbox.startedAt)
@@ -28,14 +31,17 @@ console.log('Running sandbox template id:', runningSandbox.templateId)
```python
from e2b_code_interpreter import Sandbox
+# Create a sandbox.
sandbox = Sandbox({
metadata: {
name: 'My Sandbox',
},
})
-running_sandboxes = sandbox.list() # $HighlightLine
+# List all running sandboxes.
+running_sandboxes = Sandbox.list() # $HighlightLine
running_sandbox = running_sandboxes[0]
+
print('Running sandbox metadata:', running_sandbox.metadata)
print('Running sandbox id:', running_sandbox.sandbox_id)
print('Running sandbox started at:', running_sandbox.started_at)
@@ -91,6 +97,7 @@ const runningSandboxes = await Sandbox.list({
```
```python
from e2b_code_interpreter import Sandbox
+from e2b.sandbox.sandbox_api import SandboxQuery
# Create sandbox with metadata.
sandbox = Sandbox(
@@ -112,3 +119,203 @@ running_sandboxes = Sandbox.list(
)
```
</CodeGroup>
+
+## Changes in the Beta SDKs
+
+<Note>
+If you're using the [beta version of the SDK](/docs/sandbox/installing-beta-sdks), the `Sandbox.list()` method was updated.
+</Note>
+
+### Listing sandboxes
+
+The `Sandbox.list()` method now supports pagination. In the [advanced pagination](/docs/sandbox/list#advanced-pagination) section, you can find more information about pagination techniques using the updated method.
+
+<CodeGroup>
+```js
+import { Sandbox, SandboxInfo } from '@e2b/code-interpreter'
+
+const sandbox = await Sandbox.create()
+
+const paginator = Sandbox.list() // $HighlightLine
+
+// Get the first page of sandboxes (running and paused)
+const firstPage = await paginator.nextItems() // $HighlightLine
+
+// Get the next page of sandboxes
+const nextPage = await paginator.nextItems() // $HighlightLine
+```
+```python
+from e2b_code_interpreter import Sandbox, SandboxInfo
+
+sandbox = Sandbox()
+
+paginator = Sandbox.list() # $HighlightLine
+
+# Get the first page of sandboxes (running and paused)
+firstPage = paginator.next_items() # $HighlightLine
+
+# Get the next page of sandboxes
+nextPage = paginator.next_items() # $HighlightLine
+```
+</CodeGroup>
+
+
+### Filtering sandboxes
+
+Filter sandboxes by their current state. The state parameter can contain either "**running**" for running sandboxes or "**paused**" for paused sandboxes, or both.
+
+<CodeGroup>
+```js
+import { Sandbox } from '@e2b/code-interpreter'
+
+// Create a sandbox.
+const sandbox = await Sandbox.create()
+
+// List all sandboxes that are running or paused.
+const paginator = Sandbox.list({
+ query: {
+ state: ['running', 'paused'], // $HighlightLine
+ },
+})
+
+const sandboxes = await paginator.nextItems() // $HighlightLine
+```
+```python
+from e2b_code_interpreter import Sandbox, SandboxListQuery
+
+# Create a sandbox with metadata.
+sandbox = Sandbox()
+
+# List running sandboxes that are running or paused.
+paginator = Sandbox.list(
+ query=SandboxListQuery(
+ state=['running', 'paused'], # $HighlightLine
+ ),
+)
+
+# Get the first page of sandboxes (running and paused)
+sandboxes = paginator.next_items() # $HighlightLine
+```
+</CodeGroup>
+
+Filter sandboxes by the metadata key value pairs specified during Sandbox creation.
+
+<CodeGroup>
+```js
+import { Sandbox } from '@e2b/code-interpreter'
+
+// Create sandbox with metadata.
+const sandbox = await Sandbox.create({
+ metadata: {
+ env: 'dev', // $HighlightLine
+ app: 'my-app', // $HighlightLine
+ userId: '123', // $HighlightLine
+ },
+})
+
+// List all sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
+const paginator = Sandbox.list({
+ query: {
+ metadata: { userId: '123', env: 'dev' }, // $HighlightLine
+ },
+})
+
+const sandboxes = await paginator.nextItems() // $HighlightLine
+```
+```python
+from e2b_code_interpreter import Sandbox, SandboxListQuery
+
+# Create sandbox with metadata.
+sandbox = Sandbox(
+ metadata={
+ "env": "dev", # $HighlightLine
+ "app": "my-app", # $HighlightLine
+ "user_id": "123", # $HighlightLine
+ },
+)
+
+# List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
+paginator = Sandbox.list(
+ query=SandboxListQuery(
+ metadata={
+ "userId": "123", # $HighlightLine
+ "env": "dev", # $HighlightLine
+ }
+ ),
+)
+
+# Get the first page of sandboxes (running and paused)
+sandboxes = paginator.next_items() # $HighlightLine
+```
+</CodeGroup>
+
+### Advanced pagination
+
+For more granular pagination, you can set custom per-page item limit (default and maximum is **1000**) and specify an offset parameter (`nextToken` or `next_token`) to start paginating from.
+
+<CodeGroup>
+```js
+import { Sandbox } from '@e2b/code-interpreter'
+
+const paginator = Sandbox.list({
+ limit: 1000, // $HighlightLine
+ nextToken: '<base64-encoded-token>', // $HighlightLine
+})
+
+// Additional paginator properties
+// Whether there is a next page
+paginator.hasNext
+
+// Next page token
+paginator.nextToken
+
+// Fetch the next page
+await paginator.nextItems()
+```
+```python
+from e2b_code_interpreter import Sandbox, SandboxListQuery
+
+paginator = Sandbox.list(
+ limit=1000, # $HighlightLine
+ next_token='<base64-encoded-token>', # $HighlightLine
+)
+
+# Additional paginator properties
+# Whether there is a next page
+paginator.has_next
+
+# Next page token
+paginator.next_token
+
+# Fetch the next page
+paginator.next_items()
+```
+</CodeGroup>
+
+You can fetch all pages by looping through the paginator while checking if there is a next page (using `hasNext` or `has_next` property) and fetching until there are no more pages left to fetch:
+
+<CodeGroup>
+```js
+import { Sandbox } from '@e2b/code-interpreter'
+
+const paginator = Sandbox.list()
+
+// Loop through all pages
+const sandboxes: SandboxInfo[] = []
+while (paginator.hasNext) { // $HighlightLine
+ const items = await paginator.nextItems()
+ sandboxes.push(...items)
+}
+```
+```python
+from e2b_code_interpreter import Sandbox, SandboxListQuery
+
+paginator = Sandbox.list()
+
+# Loop through all pages
+sandboxes: list[SandboxInfo] = []
+while paginator.has_next: # $HighlightLine
+ items = paginator.next_items()
+ sandboxes.extend(items)
+```
+</CodeGroup>
diff --git a/apps/web/src/app/(docs)/docs/sandbox/metadata/page.mdx b/apps/web/src/app/(docs)/docs/sandbox/metadata/page.mdx
index 3eb890e91..f1ea15983 100644
--- a/apps/web/src/app/(docs)/docs/sandbox/metadata/page.mdx
+++ b/apps/web/src/app/(docs)/docs/sandbox/metadata/page.mdx
@@ -11,6 +11,10 @@ This is useful in various scenarios, for example:
You specify metadata when creating a sandbox and can access it later through listing running sandboxes with `Sandbox.list()` method.
+<Note>
+If you're using the [beta version of the SDK](/docs/sandbox/installing-beta-sdks), the `Sandbox.list()` method was updated. See [List Sandboxes](/docs/sandbox/list#changes-in-the-beta-sdks) for more information.
+</Note>
+
<CodeGroup>
```js
import { Sandbox } from '@e2b/code-interpreter'
diff --git a/apps/web/src/app/(docs)/docs/sandbox/metrics/page.mdx b/apps/web/src/app/(docs)/docs/sandbox/metrics/page.mdx
index 54b3c0709..395c386f5 100644
--- a/apps/web/src/app/(docs)/docs/sandbox/metrics/page.mdx
+++ b/apps/web/src/app/(docs)/docs/sandbox/metrics/page.mdx
@@ -6,41 +6,19 @@ This feature is in a private beta.
The sandbox metrics allows you to get information about the sandbox's CPU and memory usage.
-## 1. Installation
+## Installation
-To get sandbox metrics, you need to install the beta version of the SDKs and CLI.
+To get sandbox metrics, you need to install the beta version of the SDKs and CLI:
-### 1.1. Installing the beta version of the SDKs
+- [Installing beta SDKs](/docs/sandbox/installing-beta-sdks)
-<CodeGroup isTerminalCommand>
-```bash {{ language: 'js' }}
-npm i @e2b/code-interpreter@beta
-#
-# or use Core: https://github.com/e2b-dev/e2b
-# npm i e2b@beta
-```
-
-```bash {{ language: 'python' }}
-pip install e2b-code-interpreter==1.2.0b1
-#
-# or use Core: https://github.com/e2b-dev/e2b
-# pip install e2b==1.2.0b1
-```
-</CodeGroup>
-
-### 1.2. Installing the beta version of the CLI
-
-<CodeGroup isTerminalCommand>
-```bash {{ language: 'bash' }}
-npm i -g @e2b/cli@beta
-```
-</CodeGroup>
+- [Installing beta CLI](/docs/cli#beta-cli)
-## 2. Getting sandbox metrics
+## Getting sandbox metrics
Getting the metrics of a sandbox returns an array of timestamped metrics containing CPU and memory usage information.
The metrics are collected at the start of the sandbox, then every 2 seconds, and finally right before the sandbox is deleted.
-### 2.1. Getting sandbox metrics using the SDKs
+### Getting sandbox metrics using the SDKs
<CodeGroup>
```js
@@ -106,7 +84,7 @@ print('Sandbox metrics', metrics)
```
</CodeGroup>
-### 2.2. Getting sandbox metrics using the CLI
+### Getting sandbox metrics using the CLI
<CodeGroup isTerminalCommand>
```bash
e2b sandbox metrics <sandbox_id> # $HighlightLine
diff --git a/apps/web/src/app/(docs)/docs/sandbox/persistence/page.mdx b/apps/web/src/app/(docs)/docs/sandbox/persistence/page.mdx
index 76ff34692..738f26ff6 100644
--- a/apps/web/src/app/(docs)/docs/sandbox/persistence/page.mdx
+++ b/apps/web/src/app/(docs)/docs/sandbox/persistence/page.mdx
@@ -2,42 +2,16 @@
<Note>
Sandbox persistence is currently in public beta:
-1. You'll need to install the [beta version of the SDKs](#1-installing-the-beta-version-of-the-sdks).
-1. Consider [some limitations](#limitations-while-in-beta).
-1. The persistence is free for all users during the beta.
+1. You'll need to install the [beta version of the SDKs](/docs/sandbox/installing-beta-sdks).
+2. Consider [some limitations](#limitations-while-in-beta).
+3. The persistence is free for all users during the beta.
</Note>
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.
-## 1. Installing the beta version of the SDKs
-To use the sandbox persistence, you need to install the beta version of the SDKs.
-
-<CodeGroup>
-```bash {{ language: 'js' }}
-npm i @e2b/code-interpreter@beta
-#
-# or use Core: https://github.com/e2b-dev/e2b
-# npm i e2b@beta
-#
-# or use Desktop: https://github.com/e2b-dev/desktop
-# npm i @e2b/desktop@beta
-```
-
-```bash {{ language: 'python' }}
-pip install e2b-code-interpreter==1.2.0b1
-#
-# or use Core: https://github.com/e2b-dev/e2b
-# pip install e2b==1.2.0b1
-#
-# or use Desktop: https://github.com/e2b-dev/desktop
-# pip install e2b-desktop==1.2.0b1
-```
-</CodeGroup>
-
-
-## 2. Pausing sandbox
+## 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.
<CodeGroup>
@@ -78,7 +52,7 @@ print('Sandbox paused', sandbox_id) # $HighlightLine
</CodeGroup>
-## 3. Resuming sandbox
+## 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.
@@ -127,6 +101,102 @@ print('Sandbox resumed', same_sbx.sandbox_id) # $HighlightLine
```
</CodeGroup>
+## 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).
+
+<CodeGroup>
+```js
+import { Sandbox, SandboxInfo } from '@e2b/code-interpreter'
+// or use Core: https://github.com/e2b-dev/e2b
+// import { Sandbox, SandboxInfo } from 'e2b'
+//
+// or use Desktop: https://github.com/e2b-dev/desktop
+// import { Sandbox, SandboxInfo } from '@e2b/desktop'
+
+// List all paused sandboxes
+const paginator = Sandbox.list({ query: { state: ['paused'] } }) // $HighlightLine
+
+// Get the first page of paused sandboxes
+const sandboxes = await paginator.nextItems() // $HighlightLine
+
+// Get all paused sandboxes
+const sandboxes: SandboxInfo[] = []
+while (paginator.hasNext) {
+ const items = await paginator.nextItems()
+ sandboxes.push(...items)
+}
+```
+```python
+from e2b_code_interpreter import Sandbox, SandboxListQuery
+# or use Core: https://github.com/e2b-dev/e2b
+# from e2b import Sandbox, SandboxListQuery
+#
+# or use Desktop: https://github.com/e2b-dev/desktop
+# from e2b_desktop import Sandbox, SandboxInfo, SandboxListQuery
+
+# List all paused sandboxes
+paginator = Sandbox.list(SandboxListQuery(state=['paused'])) # $HighlightLine
+
+# Get the first page of paused sandboxes
+sandboxes = paginator.next_items() # $HighlightLine
+
+# Get all paused sandboxes
+sandboxes: list[SandboxInfo] = []
+while paginator.has_next:
+ items = paginator.next_items()
+ sandboxes.extend(items)
+```
+</CodeGroup>
+
+## Removing paused sandboxes
+
+You can remove paused sandboxes by calling the `kill` method on the Sandbox instance.
+
+<CodeGroup>
+```js
+import { Sandbox } from '@e2b/code-interpreter'
+// or use Core: https://github.com/e2b-dev/e2b
+// import { Sandbox } from 'e2b'
+//
+// or use Desktop: https://github.com/e2b-dev/desktop
+// import { Sandbox } from '@e2b/desktop'
+
+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
+const sandboxId = await sbx.pause()
+
+// Remove the sandbox
+await sbx.kill() // $HighlightLine
+
+// Remove sandbox by id
+await Sandbox.kill(sandboxId) // $HighlightLine
+```
+```python
+from e2b import Sandbox
+# or use Core: https://github.com/e2b-dev/e2b
+# from e2b import Sandbox
+#
+# or use Desktop: https://github.com/e2b-dev/desktop
+# from e2b_desktop import Sandbox
+
+sbx = Sandbox()
+
+# Pause the sandbox
+sandbox_id = sbx.pause()
+
+# Remove the sandbox
+sbx.kill() # $HighlightLine
+
+# Remove sandbox by id
+Sandbox.kill(sandbox_id) # $HighlightLine
+```
+</CodeGroup>
+
## Sandbox's timeout
When you resume a sandbox, the sandbox's timeout is reset to the default timeout of an E2B sandbox - 5 minutes.
diff --git a/apps/web/src/components/Navigation/routes.tsx b/apps/web/src/components/Navigation/routes.tsx
index 2fac7a08a..4ac497980 100644
--- a/apps/web/src/components/Navigation/routes.tsx
+++ b/apps/web/src/components/Navigation/routes.tsx
@@ -294,7 +294,7 @@ export const docRoutes: NavGroup[] = [
href: '/docs/sandbox/environment-variables',
},
{
- title: 'List running sandboxes',
+ title: 'List sandboxes',
href: '/docs/sandbox/list',
},
{
@@ -305,6 +305,10 @@ export const docRoutes: NavGroup[] = [
title: 'Internet access',
href: '/docs/sandbox/internet-access',
},
+ {
+ title: 'Installing beta SDKs',
+ href: '/docs/sandbox/installing-beta-sdks',
+ },
// {
// title: '* Request timeouts',
// href: '/docs/sandbox/request-timeouts',