Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
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.mdxindex 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 })```-```pythonfrom 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'++// Beforeconst 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'+// Beforeconst 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++# Beforesandbox = 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-# Syncfrom 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'+// Beforeconst 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+# Beforesandbox = Sandbox()result = sandbox.process.start_and_wait(@@ -121,15 +239,19 @@ result = sandbox.process.start_and_wait(# Nowresult = 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'+// Beforeconst 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+# Beforesandbox = 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.tsxindex 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',},// {