Creating Custom Sandbox

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 spawn 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

Install CLI

npm install -g @e2b/cli@latest

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.

Login to CLI

e2b auth login

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.

We want our custom sandbox to have the ffmpeg isntalled - ffmpeg is a tool for editing video and audio files.

e2b.Dockerfile

# 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.

Build sandbox template

e2b template build --name "my-agent-sandbox"

The final output should look similar to this.

Build output

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/guide/custom-sandbox in Spawn and control your sandbox section.                                               │
│                                                                                                                                                      │
│───────────────────────────────────────────────────────────────────── Python SDK ─────────────────────────────────────────────────────────────────────│
│                                                                                                                                                      │
│  from e2b import Sandbox                                                                                                                             │
│                                                                                                                                                      │
# Start sandbox                                                                                                                                     │
│  sandbox = Sandbox("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.

e2b.toml

# 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.

Update sandbox 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()