Skip to main content
You are reading a legacy (pre v1.0) document.
In this guide, we’ll create a custom E2B sandbox with preinstalled dependencies and files. Once the sandbox is built, we’ll show how to create and control it with our SDK.

​
Prerequisites

  1. Node.js 18.0.0 or later
  2. E2B CLI
  3. Running Docker instance

​
1. Install E2B CLI

npm install -g @e2b/cli@latest
You need Node.js 18.0.0 or later to install the CLI.

​
2. Login to CLI

Before you create your first custom sandbox, you will need to authenticate in the CLI with your E2B account. Run the following command in your terminal. 
e2b auth login
You need to have an existing E2B account to login. Sign up here.

​
3. Create e2b.Dockerfile

To describe how your custom sandbox will look like, create a new Dockerfile and name it e2b.Dockerfile. We use this Dockerfile as the template file.
Run e2b template init to create e2b.Dockerfile in the current directory.
We want our custom sandbox to have the ffmpeg isntalled - ffmpeg is a tool for editing video and audio files.
We support only Debian based images at the moment.
# You can use most of the Debian based images
FROM ubuntu:22.04

# Install the ffmpeg tool/
RUN apt update \
    && apt install -y ffmpeg

​
4. Build custom sandbox

Now it’s time to create your custom sandbox based on the sandbox template file (the e2b.Dockefile file) you just created in the previous step. Run the following command inside the template file directory in your terminal.
Pro users can use the --cpu-count= (docs) and --memory-mb= (docs) flags to customize the sandbox compute. Read more about the compute here.
e2b template build --name "my-agent-sandbox"
Use the .dockerignore file to exclude files from the sandbox template.
The final output should look similar to this. 
Preparing sandbox template building (1 files in Docker build context).
Found ./e2b.Dockerfile that will be used to build the sandbox template.
Started building the sandbox template my-agent-sandbox

# Truncated for visibility
# ...
# ...

Running postprocessing. It can take up to few minutes.

Postprocessing finished.

✅ Building sandbox template my-agent-sandbox finished.

┌ Usage examples ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                                                                                      │
│  You can use E2B Python or JS SDK to spawn sandboxes now.                                                                                            │
│  Find more here - https://e2b.dev/docs/legacy/guide/custom-sandbox in Spawn and control your sandbox section.                                               │
│                                                                                                                                                      │
│───────────────────────────────────────────────────────────────────── Python SDK ─────────────────────────────────────────────────────────────────────│
│                                                                                                                                                      │
│  from e2b import Sandbox                                                                                                                             │
│                                                                                                                                                      │
│  # Start sandbox                                                                                                                                     │
│  sandbox = Sandbox.create("my-agent-sandbox")                                                                                                               │
│                                                                                                                                                      │
│  # Interact with sandbox. Learn more here:                                                                                                           │
│  # https://e2b.dev/docs/sandbox/overview                                                                                                             │
│                                                                                                                                                      │
│  # Close sandbox once done                                                                                                                           │
│  sandbox.close()                                                                                                                                     │
│                                                                                                                                                      │
│─────────────────────────────────────────────────────────────────────── JS SDK ───────────────────────────────────────────────────────────────────────│
│                                                                                                                                                      │
│  import { Sandbox } from 'e2b'                                                                                                                  │
│                                                                                                                                                      │
│  // Start sandbox                                                                                                                                    │
│  const sandbox = await Sandbox.create('my-agent-sandbox')                                                                                            │
│                                                                                                                                                      │
│  // Interact with sandbox. Learn more here:                                                                                                          │
│  // https://e2b.dev/docs/sandbox/overview                                                                                                            │
│                                                                                                                                                      │
│  // Close sandbox once done                                                                                                                          │
│  await sandbox.close()                                                                                                                               │
│                                                                                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Execution time: 42.55s
This will create the e2b.toml file storing the sandbox config. 
# This is a config for E2B sandbox template
template_id = "1wdqsf9le9gk21ztb4mo"
dockerfile = "e2b.Dockerfile"
template_name = "my-agent-sandbox"
Sandbox template nameSandbox template ID
my-agent-sandbox1wdqsf9le9gk21ztb4mo

​
Updating your sandbox template

If you want to update your sandbox template, you run the same command you did to build it. This will rebuild the template. 
e2b template build

​
5. Spawn and control your sandbox

Now you can use the E2B SDK to spawn & control your new custom sandbox. The sandbox template name is my-agent-sandbox. We’ll use it as an unique identifier and pass it to the SDK as the template parameter. This way, we’ll be able to spawn our custom sandbox and control it with the SDK.
Spawn & control your custom sandbox
import { Sandbox } from 'e2b'

// Spawn your custom sandbox
const sandbox = await Sandbox.create({ template: 'my-agent-sandbox' })

// Interact with sandbox. Learn more here:
// https://e2b.dev/docs/sandbox/overview

// Close sandbox once done
await sandbox.close()