Skip to content

armgit / E2B

Public Imported from GitHub
0

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

Add first version of migration guide

Tomas Valentaa41cd9398de6
diff --git a/apps/web/src/app/(docs)/docs/guide/beta-migration/page.mdx b/apps/web/src/app/(docs)/docs/guide/beta-migration/page.mdx
index e2a754082..8a6ca5e09 100644
--- a/apps/web/src/app/(docs)/docs/guide/beta-migration/page.mdx
+++ b/apps/web/src/app/(docs)/docs/guide/beta-migration/page.mdx
@@ -1,100 +1,215 @@
# SDK Beta Migration Guide
+The following guide shows how to migrate your code from the current core SDKs (`e2b`) and Code Interpreter SDKs (`@e2b/code-interpreter`/`e2b-code-interpreter`) to the Beta versions.
-### Create sandbox
+The latest beta versions you should install can be found in NPM/PyPi release history:
+- JS/TS
+ - Latest release with *rc* tag for [`e2b`](https://www.npmjs.com/package/e2b?activeTab=versions)
+ - Latest release with *rc* tag for [`@e2b/code-interpreter`](https://www.npmjs.com/package/@e2b/code-interpreter?activeTab=versions)
+- Python
+ - Latest *PRE-RELEASE* for [`e2b`](https://pypi.org/project/e2b/#history)
+ - Latest *PRE-RELEASE* for [`e2b-code-interpreter`](https://pypi.org/project/e2b-code-interpreter/#history)
+
+<Note>
+If you are using a custom template you need to rebuild it with `"/root/.jupyter/start-up.sh"` as the start command while using the latest `FROM e2bdev/code-interpreter:latest`
+or including all relevant files in the [Beta template](https://github.com/e2b-dev/code-interpreter/tree/beta/template) directory.
+</Note>
+
+## Core Sandbox SDK changes
+These changes affect both the `e2b` core SDKs and Code Interpreter SDKs (`@e2b/code-interpreter`/`e2b-code-interpreter`) because the Code Interpreter uses the core SDK.
+
+### Creating sandbox
+
+When creating a sandbox you now **specify the sandbox timeout** — that is how long the sandbox will exist. If you don't specify the timeout the sandbox will be closed after 5 minutes.
+
+You also no longer call the `.close()` method when you are done with the sandbox. Sandbox will be automatically closed and killed after the timeout.
+
+You can still use `.kill()` to kill the sandbox immediately if you are sure you won't need it anymore.
<CodeGroup isRunnable={false}>
```js
-import { Sandbox } from 'e2b'
+import Sandbox from 'e2b'
// Before
-const sandbox = await Sandbox.create({ template: 'my-template'})
+const sandbox = await Sandbox.create()
await sandbox.close()
// Now
-const sandbox = await Sandbox.create('my-template', { timeoutMs: 5*60*1000 })
+const sandbox = await Sandbox.create({ timeoutMs: 300_000 })
```
-
```python
from e2b import Sandbox
# Before
-sandbox = Sandbox(template='my-template')
+sandbox = Sandbox()
sandbox.close()
# Now
-sandbox = Sandbox(template='my-template', timeout=10*60*1000)
+sandbox = Sandbox(timeout=300)
```
</CodeGroup>
-### Extend sandbox lifetime
+If you need to use a custom sandbox template you pass the template as the first parameter:
<CodeGroup isRunnable={false}>
```js
-// Before
-const sandbox = await Sandbox.create({ timeoutMs: 5*60*1000 })
+import Sandbox from 'e2b'
-await sandbox.keepAlive(10 * 60 * 1000)
+// Before
+const sandbox = await Sandbox.create({ template: 'my-template' })
await sandbox.close()
// Now
+const sandbox = await Sandbox.create('my-template', {
+ timeoutMs: 300_000,
+})
+```
+```python
+from e2b import Sandbox
+
+# Before
+sandbox = Sandbox(template='my-template')
+sandbox.close()
+
+# Now
+sandbox = Sandbox(template='my-template', timeout=300)
+```
+</CodeGroup>
+
+### Changing sandbox timeout
+If you need to modify the sandbox timeout after creating it you can use `.setTimeout()`/`.set_timeout()` method.
+It will set the timeout to the specified value regardless of the current timeout value.
+
+<CodeGroup isRunnable={false}>
+```js
+import Sandbox from 'e2b'
+
+// Before
const sandbox = await Sandbox.create()
-await sandbox.setTimeout(10 * 60 * 1000)
+await sandbox.keepAlive(600_000)
+
+// Now
+const sandbox = await Sandbox.create({ timeoutMs: 300_000 })
+await sandbox.setTimeout(600_000)
```
```python
+from e2b import Sandbox
+
# Before
-sandbox = Sandbox(timeout)
+sandbox = Sandbox()
+sandbox.keep_alive(600)
# Now
-sandbox = Sandbox(timeout=5*60)
-sandbox.set_timeout(10 * 60)
+sandbox = Sandbox(timeout=300)
+sandbox.set_timeout(600)
```
</CodeGroup>
### Reconnecting
+When connection to an existing sandbox use `.connect()`/`.connect()` method instead of `.reconnect()`/`.reconnect()`.
+
+Instead of using `.keepAlive()`/`.keep_alive()` method to prevent the sandbox from closing until you reconnect use `.setTimeout()`/`.set_timeout()` method.
+Because the timeout is set when the sandbox is created, you may not need to set the timeout when reconnecting at all now.
+
<CodeGroup isRunnable={false}>
```js
+import Sandbox from 'e2b'
+
// Before
const sandbox = await Sandbox.create()
-await sandbox.keepAlive(10 * 60 * 1000)
+await sandbox.keepAlive(600_000)
await sandbox.close()
const existingSandbox = await Sandbox.reconnect(sandbox.id)
// Now
-const sandbox = await Sandbox.create()
-await sandbox.setTimeout(10 * 60 * 1000)
+const sandbox = await Sandbox.create({ timeoutMs: 600_000 })
const existingSandbox = await Sandbox.connect(sandbox.sandboxID)
```
```python
+from e2b import Sandbox
+
+# Before
sandbox = Sandbox()
-sandbox.set_timeout(10 * 60)
+sandbox.keep_alive(600)
+sandbox.close()
+
+existing_sandbox = Sandbox.reconnect(sandbox.id)
+
+# Now
+sandbox = Sandbox(timeout=600)
existing_sandbox = Sandbox.connect(sandbox.sandbox_id)
```
</CodeGroup>
-### Python Async
+### Uploading files or data
+Use `.files.write()` method to upload files to the sandbox.
+
+The method accepts `path` in the sandbox as the first argument and the `data` as the second argument.
+
<CodeGroup isRunnable={false}>
+```js
+import Sandbox from 'e2b'
+
+// Before
+const content = fs.readFileSync('local-path')
+await sandbox.uploadFile(content, 'path-in-sandbox')
+
+// Now
+const content = fs.readFileSync('local-path')
+await sandbox.files.write('path-in-sandbox', content)
+```
```python
-# Sync
from e2b import Sandbox
-from e2b_code_interpreter import CodeInterpreter
-sandbox = Sandbox()
-sandbox = CodeInterpreter()
+# Before
+with open("path/to/local/file", "rb") as file:
+ sandbox.upload_file(file)
-# Async
-from e2b import AsyncSandbox
-from e2b_code_interpreter import AsyncCodeInterpreter
+# Now
+with open("path/to/local/file", "rb") as file:
+ sandbox.files.write("path-in-sandbox", file)
+```
+</CodeGroup>
-sandbox = await AsyncSandbox.create()
-sandbox = await AsyncCodeInterpreter.create()
+### Downloading files
+Use `.files.read()` method to download files from the sandbox.
+
+The method accepts `path` in the sandbox as the first argument and optional `format` as the second argument.
+
+<CodeGroup isRunnable={false}>
+```js
+import Sandbox from 'e2b'
+
+// Before
+const content = await sandbox.downloadFile('path-in-sandbox')
+
+// Now
+const content = await sandbox.files.read('path-in-sandbox')
+```
+```python
+from e2b import Sandbox
+
+# Before
+content = sandbox.download_file('path-in-sandbox')
+
+# Now
+content = sandbox.files.read("path-in-sandbox")
```
</CodeGroup>
+
### Running process
+You execute processes by calling `.commands.run()` method. By default, the method waits for the command to finish.
+
+You can specify the timeout for the command execution by passing `timeoutMs`/`timeout` option. The default timeout is 60 seconds.
+
+If the command fails with a non-zero exit a `ProcessExitError`/`ProcessExitException` is raised and you can catch and inspect the error for more info.
+
<CodeGroup isRunnable={false}>
```js
+import Sandbox from 'e2b'
+
// Before
const sandbox = await Sandbox.create()
const result = await sandbox.process.startAndWait({
@@ -107,9 +222,12 @@ const result = await sandbox.process.startAndWait({
const result = await sandbox.commands.run('echo "Hello, World!"', {
onStderr(output) { console.log(output) },
onStdout(output) { console.log(output) },
+ timeoutMs: 60_000,
})
```
```python
+from e2b import Sandbox
+
# Before
sandbox = Sandbox()
result = sandbox.process.start_and_wait(
@@ -121,15 +239,19 @@ result = sandbox.process.start_and_wait(
# Now
result = sandbox.commands.run(
cmd='echo "Hello, World!"',
+ timeout=60,
on_stdout=lambda output: print(output),
on_stderr=lambda output: print(output),
)
```
</CodeGroup>
+If you want to run the command in the background use `background: true`/`background=True` option.
+You can then use `.wait()` method to wait for the command to finish.
-### Running process in the background
<CodeGroup isRunnable={false}>
```js
+import Sandbox from 'e2b'
+
// Before
const sandbox = await Sandbox.create()
const process = await sandbox.process.start({
@@ -149,6 +271,8 @@ const command = await sandbox.commands.run('sleep 10; echo "Hello, world!"', {
const result = await command.wait()
```
```python
+from e2b import Sandbox
+
# Before
sandbox = Sandbox()
process = sandbox.process.start(
@@ -172,48 +296,166 @@ result = command.wait(
```
</CodeGroup>
-### Uploading files
+
+### Watching files changes
+
<CodeGroup isRunnable={false}>
```js
+import Sandbox from 'e2b'
+
// Before
-await sandbox.uploadFile(
- Buffer.from('Hello, world!'),
- 'path-in-sandbox',
-)
+const sandbox = await Sandbox.create()
+const watcher = sandbox.filesystem.watchDir('path-in-sandbox')
+watcher.addEventListener((event) => console.log(event))
+await watcher.start()
// Now
-const content = await sandbox.files.write(
-'/path-in-sandbox', )
+const sandbox = await Sandbox.create()
+await sandbox.files.watch('path-in-sandbox', (event) => console.log(event))
```
```python
+from e2b import Sandbox
+
# Before
-content = sandbox.download_file('/path-in-sandbox')
+sandbox = Sandbox()
+
+watcher = sandbox.filesystem.watch_dir("path-in-sandbox")
+watcher.add_event_listener(lambda event: print(event))
+watcher.start()
# Now
-content = sandbox.files.read("/path-in-sandbox")
+sandbox = Sandbox()
+watcher = sandbox.files.watch("path-in-sandbox")
+
+for event in watcher:
+ print(event)
```
</CodeGroup>
-### Downloading files
+### Accessing sandbox ID
+The `id` property on the sandbox/code interpreter instance is now named `sandboxID`/`sandbox_id`.
+
+<CodeGroup isRunnable={false}>
+```js
+import Sandbox from 'e2b'
+
+// Before
+const sandboxID = await sandbox.id
+
+// Now
+const sandboxID = await sandbox.sandboxID
+```
+```python
+from e2b import Sandbox
+
+# Before
+sandbox_id = sandbox.id
+
+# Now
+sandbox_id = sandbox.sandbox_id
+```
+</CodeGroup>
+
+### Getting sandbox upload URL
+The `.fileURL`/`.file_url()` is now `.uploadURL`/`.upload_url()` method that takes an optional argument that specifies the path in the sandbox where the file will be uploaded.
+
+If the path is not specified the file will be uploaded to the home dir — `/home/user`.
+
<CodeGroup isRunnable={false}>
```js
+import Sandbox from 'e2b'
+
// Before
-const content = await sandbox.downloadFile('/path-in-sandbox')
+const url = await sandbox.fileURL
// Now
-const content = await sandbox.files.read('/path-in-sandbox')
+const url = await sandbox.uploadUrl('path-in-sandbox')
```
```python
+from e2b import Sandbox
+
# Before
-content = sandbox.download_file('/path-in-sandbox')
+url = sandbox.file_url()
# Now
-content = sandbox.files.read("/path-in-sandbox")
+url = sandbox.upload_url('path-in-sandbox')
```
</CodeGroup>
-### Timeouts
+### Configuring sandbox `cwd`
+Previously you could set the sandbox working directory by passing `cwd` option when creating the sandbox.
+Right now this is not supported because it leads to subtle bugs especially when reconnecting to an existing sandbox.
+
+
+## Code Interpreter SDK changes
+All the previously mentioned changes to the core SDK also apply to the Code Interpreter SDK.
+Apart from them, the changes to the Code Interpreter SDK are very minimal:
+
+### Executing code
+When executing code via JS/TS Code Interpreter SDK you now pass the `timeoutMs` option to the `execCell` method instead of `timeout`.
+
+The default timeout for the code execution is now 300 seconds.
-### Custom sandbox templates
+<CodeGroup isRunnable={false}>
+```js
+import CodeInterpreter from '@e2b/code-interpreter'
+
+// Before
+const sandbox = await CodeInterpreter.create()
+const execution = await sandbox.notebook.execCell('print("Hello, world!")', {
+ timeout: 2000,
+})
+await sandbox.close()
+
+// Now
+const sandbox = await CodeInterpreter.create({ timeoutMs: 300_000 })
+const execution = await sandbox.notebook.execCell('print("Hello, world!")', {
+ timeoutMs: 2000,
+})
+```
+
+```python
+from e2b_code_interpreter import CodeInterpreter
+
+# Before
+sandbox = CodeInterpreter()
+execution = sandbox.notebook.exec_cell('print("Hello, world!")', timeout=2)
+sandbox.close()
+
+# Now
+sandbox = CodeInterpreter(timeout=300)
+execution = sandbox.notebook.exec_cell('print("Hello, world!")', timeout=2)
+```
+</CodeGroup>
+
+
+## Python Async
+Python core SDK and Code Interpter SDK now support async.
+
+If you need to use async import `AsyncSandbox`/`AsyncCodeInterpreter` instead of `Sandbox`/`CodeInterpreter`.
+
+Most methods behave the same in the async and sync versions.
+
+<CodeGroup isRunnable={false}>
+```python
+# Sync
+from e2b import Sandbox
+sandbox = Sandbox()
+
+from e2b_code_interpreter import CodeInterpreter
+sandbox = CodeInterpreter()
+
+# Async
+from e2b import AsyncSandbox
+from e2b_code_interpreter import AsyncCodeInterpreter
+
+sandbox = await AsyncSandbox.create()
+sandbox = await AsyncCodeInterpreter.create()
+```
+</CodeGroup>
-### Sandbox file upload
+## Timeouts
+There are now two types of timeouts that you can pass as parameters:
+1. `request_timeout`/`requestTimeoutMs` sets how long the operation should wait for connection/processing.
+This is useful for ensuring that none of the sandbox operations hang indefinitely.
+2. `timeout`/`timeoutMs` which is used for setting the maximum length of long-running operations like executing code, running processes, or the sandbox itself.
diff --git a/apps/web/src/components/Navigation/routes.tsx b/apps/web/src/components/Navigation/routes.tsx
index 274665088..cfa7008fc 100644
--- a/apps/web/src/components/Navigation/routes.tsx
+++ b/apps/web/src/components/Navigation/routes.tsx
@@ -25,6 +25,7 @@ import {
Variable,
Wrench,
BookOpen,
+ List,
} from 'lucide-react'
import Image from 'next/image'
@@ -90,8 +91,8 @@ export const routes = [
href: 'https://github.com/e2b-dev/e2b-cookbook',
},
{
- icon: <Hammer strokeWidth={1} size={20} />,
- title: 'Beta SDK Migration',
+ icon: <List strokeWidth={1} size={20} />,
+ title: 'SDK Beta Migration',
href: '/docs/guide/beta-migration',
},
// {