diff --git a/docs/sandbox-template.mdx b/docs/sandbox-template.mdx index 3b7c845..471e0b5 100644 --- a/docs/sandbox-template.mdx +++ b/docs/sandbox-template.mdx @@ -1,142 +1,143 @@ ---- -title: "Sandbox templates" -sidebarTitle: Sandbox customization ---- - -import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; - - - -Sandbox templates allow you to customize the sandbox environment to your needs. - -To create a sandbox template, you specify the `e2b.Dockerfile`. We then take this Dockerfile and create a new sandbox template from it and give you back a template ID. - -You can then use this template ID to create a new sandbox with the SDK based on the template you created. - -## How to create custom sandbox - -**Steps** -1. [Install E2B CLI](#1-install-e2b-cli) -1. [Initialize sandbox template](#2-initialize-sandbox-template) -1. [Customize `e2b.Dockerfile`](#3-customize-e2b-dockerfile) -1. [Build your sandbox template](#4-build-your-sandbox-template) -1. [Start your custom sandbox](#5-start-your-custom-sandbox) - - -### 1. Install E2B CLI - -**Using Homebrew (on macOS)** - - - ```bash Homebrew - brew install e2b - ``` - - -**Using NPM** - - - ```bash NPM - npm i -g @e2b/cli - ``` - - -### 2. Initialize sandbox template -The following command will create a basic `e2b.Dockerfile` in the current directory. - - - ```bash bash - e2b template init - ``` - - -### 3. Customize `e2b.Dockerfile` -Now you can customize your sandbox template by editing the `e2b.Dockerfile` file. - - ```bash e2b.Dockerfile highlight={2,5} - # Make sure to use this base image - FROM e2bdev/code-interpreter:latest - - # Install some Python packages - RUN pip install cowsay - ``` - - - - Only [Debian-based](https://en.wikipedia.org/wiki/List_of_Linux_distributions#Debian-based) images - (e.g., Debian, Ubuntu, or [E2B images](https://hub.docker.com/u/e2bdev)) are supported. - - -### 4. Build your sandbox template -Now you can build your sandbox template. We'll use Docker and the E2B CLI. -What is going to happen is that E2B CLI will call Docker to build the image and then push it to the E2B cloud. -Then we convert the Docker image to a micro VM that can be then launched as a sandbox with our SDK. - - - ```bash bash - e2b template build -c "/root/.jupyter/start-up.sh" - ``` - - -This process will take a moment. In the end, you'll see your template ID that you'll need to use to create a sandbox with the SDK. - -### 5. Start your custom sandbox -Now you can use the template ID to create a sandbox with the SDK. - - - ```javascript JavaScript & TypeScript highlight={4,6} - import { Sandbox } from '@e2b/code-interpreter' - - // Your template ID from the previous step - const templateID = 'id-of-your-template' - // Pass the template ID to the `Sandbox.create` method - const sandbox = await Sandbox.create(templateID) - - // The template installed cowsay, so we can use it - const execution = await sandbox.runCode(` - import cowsay - cowsay.say('Hello from E2B!') - `) - - console.log(execution.stdout) - ``` - ```python Python highlight={4,6} - from e2b_code_interpreter import Sandbox - - # Your template ID from the previous step - template_id = 'id-of-your-template' - # Pass the template ID to the `Sandbox.create` method - sandbox = Sandbox.create(template_id) - - # The template installed cowsay, so we can use it - execution = sandbox.run_code(""" - import cowsay - cowsay.say('Hello from E2B!') - """) - - print(execution.stdout) - ``` - - -## How it works -Every time you are building a sandbox template, we create a container based on the [`e2b.Dockerfile`](/docs/sandbox-template#3-customize-e2b-dockerfile) file you create in the process. -We extract the container's filesystem, do provisioning and configuration (e.g. installing required dependencies), and start a sandbox. - -Then, these steps happen: - - 1. We take the running sandbox. - 2. (Only if you specified the [start command](/docs/sandbox-template/start-cmd), otherwise this step is skipped) Execute the start command. - 3. Wait for readiness (by default 20 seconds if start command is specified, otherwise immediately ready). Readiness check can be configured using [ready command](/docs/sandbox-template/ready-cmd). - 4. Snapshot the sandbox and make it ready for you to spawn it with the SDK. - -We call this sandbox snapshot a _sandbox template_. - - - **Sandbox Snapshot** - - Snapshots are saved running sandboxes. We serialize and save the whole sandbox's filesystem together with all the - running processes in a way that can be loaded later. - - This allows us to load the sandbox in a few hundred milliseconds any time later with all the processes already running - and the filesystem exactly as it was. - +--- +title: "Sandbox templates" +sidebarTitle: Sandbox customization +noindex: true +--- + +import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; + + + +Sandbox templates allow you to customize the sandbox environment to your needs. + +To create a sandbox template, you specify the `e2b.Dockerfile`. We then take this Dockerfile and create a new sandbox template from it and give you back a template ID. + +You can then use this template ID to create a new sandbox with the SDK based on the template you created. + +## How to create custom sandbox + +**Steps** +1. [Install E2B CLI](#1-install-e2b-cli) +1. [Initialize sandbox template](#2-initialize-sandbox-template) +1. [Customize `e2b.Dockerfile`](#3-customize-e2b-dockerfile) +1. [Build your sandbox template](#4-build-your-sandbox-template) +1. [Start your custom sandbox](#5-start-your-custom-sandbox) + + +### 1. Install E2B CLI + +**Using Homebrew (on macOS)** + + + ```bash Homebrew + brew install e2b + ``` + + +**Using NPM** + + + ```bash NPM + npm i -g @e2b/cli + ``` + + +### 2. Initialize sandbox template +The following command will create a basic `e2b.Dockerfile` in the current directory. + + + ```bash bash + e2b template init + ``` + + +### 3. Customize `e2b.Dockerfile` +Now you can customize your sandbox template by editing the `e2b.Dockerfile` file. + + ```bash e2b.Dockerfile highlight={2,5} + # Make sure to use this base image + FROM e2bdev/code-interpreter:latest + + # Install some Python packages + RUN pip install cowsay + ``` + + + + Only [Debian-based](https://en.wikipedia.org/wiki/List_of_Linux_distributions#Debian-based) images + (e.g., Debian, Ubuntu, or [E2B images](https://hub.docker.com/u/e2bdev)) are supported. + + +### 4. Build your sandbox template +Now you can build your sandbox template. We'll use Docker and the E2B CLI. +What is going to happen is that E2B CLI will call Docker to build the image and then push it to the E2B cloud. +Then we convert the Docker image to a micro VM that can be then launched as a sandbox with our SDK. + + + ```bash bash + e2b template build -c "/root/.jupyter/start-up.sh" + ``` + + +This process will take a moment. In the end, you'll see your template ID that you'll need to use to create a sandbox with the SDK. + +### 5. Start your custom sandbox +Now you can use the template ID to create a sandbox with the SDK. + + + ```javascript JavaScript & TypeScript highlight={4,6} + import { Sandbox } from '@e2b/code-interpreter' + + // Your template ID from the previous step + const templateID = 'id-of-your-template' + // Pass the template ID to the `Sandbox.create` method + const sandbox = await Sandbox.create(templateID) + + // The template installed cowsay, so we can use it + const execution = await sandbox.runCode(` + import cowsay + cowsay.say('Hello from E2B!') + `) + + console.log(execution.stdout) + ``` + ```python Python highlight={4,6} + from e2b_code_interpreter import Sandbox + + # Your template ID from the previous step + template_id = 'id-of-your-template' + # Pass the template ID to the `Sandbox.create` method + sandbox = Sandbox.create(template_id) + + # The template installed cowsay, so we can use it + execution = sandbox.run_code(""" + import cowsay + cowsay.say('Hello from E2B!') + """) + + print(execution.stdout) + ``` + + +## How it works +Every time you are building a sandbox template, we create a container based on the [`e2b.Dockerfile`](/docs/sandbox-template#3-customize-e2b-dockerfile) file you create in the process. +We extract the container's filesystem, do provisioning and configuration (e.g. installing required dependencies), and start a sandbox. + +Then, these steps happen: + + 1. We take the running sandbox. + 2. (Only if you specified the [start command](/docs/sandbox-template/start-cmd), otherwise this step is skipped) Execute the start command. + 3. Wait for readiness (by default 20 seconds if start command is specified, otherwise immediately ready). Readiness check can be configured using [ready command](/docs/sandbox-template/ready-cmd). + 4. Snapshot the sandbox and make it ready for you to spawn it with the SDK. + +We call this sandbox snapshot a _sandbox template_. + + + **Sandbox Snapshot** + + Snapshots are saved running sandboxes. We serialize and save the whole sandbox's filesystem together with all the + running processes in a way that can be loaded later. + + This allows us to load the sandbox in a few hundred milliseconds any time later with all the processes already running + and the filesystem exactly as it was. + diff --git a/docs/sandbox-template/customize-cpu-ram.mdx b/docs/sandbox-template/customize-cpu-ram.mdx index 166b647..b0e9245 100644 --- a/docs/sandbox-template/customize-cpu-ram.mdx +++ b/docs/sandbox-template/customize-cpu-ram.mdx @@ -1,22 +1,23 @@ ---- -title: "Customize sandbox CPU & RAM" -sidebarTitle: Customize CPU & RAM ---- - -import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; - - - -You can customize the CPU and RAM of your sandbox template via E2B CLI. - -You'll need to create a sandbox [template first](/docs/sandbox-template). - -During the build step, you can specify the CPU and RAM of your sandbox template. - -The following command will create a sandbox template with 2 CPUs and 2GB of RAM. - - -```bash Terminal -e2b template build -c "/root/.jupyter/start-up.sh" --cpu-count 2 --memory-mb 2048 -``` - +--- +title: "Customize sandbox CPU & RAM" +sidebarTitle: Customize CPU & RAM +noindex: true +--- + +import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; + + + +You can customize the CPU and RAM of your sandbox template via E2B CLI. + +You'll need to create a sandbox [template first](/docs/sandbox-template). + +During the build step, you can specify the CPU and RAM of your sandbox template. + +The following command will create a sandbox template with 2 CPUs and 2GB of RAM. + + +```bash Terminal +e2b template build -c "/root/.jupyter/start-up.sh" --cpu-count 2 --memory-mb 2048 +``` + diff --git a/docs/sandbox-template/ready-cmd.mdx b/docs/sandbox-template/ready-cmd.mdx index 76ae653..fc721cd 100644 --- a/docs/sandbox-template/ready-cmd.mdx +++ b/docs/sandbox-template/ready-cmd.mdx @@ -1,55 +1,56 @@ ---- -title: "Ready Command" -sidebarTitle: Ready command ---- - -import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; - - - -The ready command allows you to specify a command that will determine **template sandbox** readiness before a [snapshot](/docs/sandbox-template#how-it-works) is created. -It is executed in an infinite loop until it returns a successful **exit code 0**. -This way you can control how long should we wait for the [start command](/docs/sandbox-template/start-cmd) or any system state. - - -## How to add ready command - -When you are building a sandbox template you can specify the ready command by using the [`--ready-cmd`](https://e2b.dev/docs/sdk-reference/cli/v1.5.0/template#e2b-template-build) option: - -```bash -e2b template build --ready-cmd "" -``` - -### Sandbox template config -You can specify the ready command inside the `e2b.toml` in the same directory where you run `e2b template build`. - - ```toml e2b.toml highlight={5} - # This is a config for E2B sandbox template - template_id = "1wdqsf9le9gk21ztb4mo" - dockerfile = "e2b.Dockerfile" - template_name = "my-agent-sandbox" - ready_cmd = "" - ``` - - -## Default values -By default, the ready command is set to `sleep 0`, which means the sandbox template will be ready immediately. -If the [start command](/docs/sandbox-template/start-cmd) is defined, the default is set to `sleep 20`, which means that the template sandbox will wait for 20 seconds before taking the snapshot. - -## Examples -Here are some examples of the ready command you can use. - -### Wait for URL to return 200 status code -```bash -ready_cmd = 'curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 | grep -q "200"' -``` - -### Wait for a specific process to start -```bash -ready_cmd = 'pgrep my-process-name > /dev/null' -``` - -### Wait for a file to exist -```bash -ready_cmd = '[ -f /tmp/ready.flag ]' -``` +--- +title: "Ready Command" +sidebarTitle: Ready command +noindex: true +--- + +import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; + + + +The ready command allows you to specify a command that will determine **template sandbox** readiness before a [snapshot](/docs/sandbox-template#how-it-works) is created. +It is executed in an infinite loop until it returns a successful **exit code 0**. +This way you can control how long should we wait for the [start command](/docs/sandbox-template/start-cmd) or any system state. + + +## How to add ready command + +When you are building a sandbox template you can specify the ready command by using the [`--ready-cmd`](https://e2b.dev/docs/sdk-reference/cli/v1.5.0/template#e2b-template-build) option: + +```bash +e2b template build --ready-cmd "" +``` + +### Sandbox template config +You can specify the ready command inside the `e2b.toml` in the same directory where you run `e2b template build`. + + ```toml e2b.toml highlight={5} + # This is a config for E2B sandbox template + template_id = "1wdqsf9le9gk21ztb4mo" + dockerfile = "e2b.Dockerfile" + template_name = "my-agent-sandbox" + ready_cmd = "" + ``` + + +## Default values +By default, the ready command is set to `sleep 0`, which means the sandbox template will be ready immediately. +If the [start command](/docs/sandbox-template/start-cmd) is defined, the default is set to `sleep 20`, which means that the template sandbox will wait for 20 seconds before taking the snapshot. + +## Examples +Here are some examples of the ready command you can use. + +### Wait for URL to return 200 status code +```bash +ready_cmd = 'curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 | grep -q "200"' +``` + +### Wait for a specific process to start +```bash +ready_cmd = 'pgrep my-process-name > /dev/null' +``` + +### Wait for a file to exist +```bash +ready_cmd = '[ -f /tmp/ready.flag ]' +``` diff --git a/docs/sandbox-template/start-cmd.mdx b/docs/sandbox-template/start-cmd.mdx index 4c7ef66..8f78825 100644 --- a/docs/sandbox-template/start-cmd.mdx +++ b/docs/sandbox-template/start-cmd.mdx @@ -1,51 +1,52 @@ ---- -title: "Start Command" -sidebarTitle: Start command ---- - -import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; - - - -The start command allows you to specify a command that will be **already running** when you spawn your custom sandbox. -This way, you can for example have running servers or seeded databases inside the sandbox that are already fully ready when you spawn the sandbox using the SDK and with zero waiting time for your users during the runtime. - -The idea behind the start command feature is to lower the wait times for your users and have everything ready for your users when you spawn your sandbox. - -You can see how it works [here](/docs/sandbox-template#how-it-works). - -## How to add start command - -When you are building a sandbox template you can specify the start command by using the [`-c`](https://e2b.dev/docs/sdk-reference/cli/v1.0.9/template#e2b-template-build) option: - -```bash -e2b template build -c "" -``` - -When you spawn the custom sandbox you built, the start command will be already running if there was no error when we tried to execute it. - -### Sandbox template config -You can specify the start command also inside the `e2b.toml` in the same directory where you run `e2b template build`. - - ```toml e2b.toml highlight={5} - # This is a config for E2B sandbox template - template_id = "1wdqsf9le9gk21ztb4mo" - dockerfile = "e2b.Dockerfile" - template_name = "my-agent-sandbox" - start_cmd = "" - ``` - - - -## Logs -You can retrieve the start command's logs using the CLI: - - -```bash bash -e2b sandbox logs -``` - - - -These logs include logs from the start command during the build phase. - +--- +title: "Start Command" +sidebarTitle: Start command +noindex: true +--- + +import LegacyWarningBuildSystem from "/snippets/LegacyWarningBuildSystem.mdx"; + + + +The start command allows you to specify a command that will be **already running** when you spawn your custom sandbox. +This way, you can for example have running servers or seeded databases inside the sandbox that are already fully ready when you spawn the sandbox using the SDK and with zero waiting time for your users during the runtime. + +The idea behind the start command feature is to lower the wait times for your users and have everything ready for your users when you spawn your sandbox. + +You can see how it works [here](/docs/sandbox-template#how-it-works). + +## How to add start command + +When you are building a sandbox template you can specify the start command by using the [`-c`](https://e2b.dev/docs/sdk-reference/cli/v1.0.9/template#e2b-template-build) option: + +```bash +e2b template build -c "" +``` + +When you spawn the custom sandbox you built, the start command will be already running if there was no error when we tried to execute it. + +### Sandbox template config +You can specify the start command also inside the `e2b.toml` in the same directory where you run `e2b template build`. + + ```toml e2b.toml highlight={5} + # This is a config for E2B sandbox template + template_id = "1wdqsf9le9gk21ztb4mo" + dockerfile = "e2b.Dockerfile" + template_name = "my-agent-sandbox" + start_cmd = "" + ``` + + + +## Logs +You can retrieve the start command's logs using the CLI: + + +```bash bash +e2b sandbox logs +``` + + + +These logs include logs from the start command during the build phase. +