Skip to Content
Quickstart

Last Updated: 3/7/2026

Template Quickstart

Learn how to create custom sandbox templates to pre-configure your execution environments.

What is a Template?

A template defines what environment a sandbox starts with. It’s like a snapshot of a configured Linux system that can be instantly created when you need it.

Benefits:

  • Faster sandbox startup (pre-installed dependencies)
  • Consistent environments across sandboxes
  • Version control for your infrastructure
  • Reduced runtime configuration

Creating Your First Template

1. Create Template Definition

Create a file called e2b.Dockerfile:

# Start from Ubuntu base image
FROM ubuntu:22.04
 
# Install Python and dependencies
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    git
 
# Install Python packages
RUN pip3 install \
    pandas \
    numpy \
    matplotlib \
    scikit-learn
 
# Set working directory
WORKDIR /home/user

2. Build the Template

Using the E2B CLI:

# Install CLI
npm install -g @e2b/cli
 
# Login
e2b auth login
 
# Build template
e2b template build

This will:

  1. Build your template
  2. Upload it to E2B
  3. Return a template ID

3. Use the Template

import { Sandbox } from 'e2b'
 
const sandbox = await Sandbox.create({
  template: 'your-template-id' // Use your template ID
})
 
// Python and all packages are already installed!
const result = await sandbox.commands.run('python3 -c "import pandas; print(pandas.__version__)"')
console.log(result.stdout)
 
await sandbox.close()

Template Structure

Basic Template

FROM ubuntu:22.04
 
# System packages
RUN apt-get update && apt-get install -y \
    curl \
    wget \
    git
 
# Application setup
WORKDIR /home/user

Node.js Template

FROM ubuntu:22.04
 
# Install Node.js
RUN apt-get update && apt-get install -y curl
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
RUN apt-get install -y nodejs
 
# Install global packages
RUN npm install -g typescript ts-node
 
# Set working directory
WORKDIR /home/user

Python Data Science Template

FROM ubuntu:22.04
 
# Install Python
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-dev
 
# Install data science stack
RUN pip3 install --no-cache-dir \
    jupyter \
    pandas \
    numpy \
    matplotlib \
    seaborn \
    scikit-learn \
    scipy
 
WORKDIR /home/user

Full Stack Template

FROM ubuntu:22.04
 
# Install system dependencies
RUN apt-get update && apt-get install -y \
    curl \
    git \
    build-essential \
    postgresql-client \
    redis-tools
 
# Install Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
RUN apt-get install -y nodejs
 
# Install Python
RUN apt-get install -y python3 python3-pip
 
# Install global tools
RUN npm install -g pnpm yarn
RUN pip3 install poetry
 
WORKDIR /home/user

Template Configuration

e2b.toml

Create an e2b.toml file for additional configuration:

[template]
name = "my-template"
description = "Custom Python environment"
 
[template.build]
dockerfile = "e2b.Dockerfile"
 
[template.resources]
cpu = 2
memory = 2048  # MB
disk = 10240   # MB

Managing Templates

List Templates

e2b template list

Delete Template

e2b template delete <template-id>

Update Template

Make changes to your e2b.Dockerfile and rebuild:

e2b template build

This creates a new version while keeping the same template ID.

Template Versioning

Tags

Use tags to version your templates:

# Build with tag
e2b template build --tag v1.0.0
 
# Use specific version
const sandbox = await Sandbox.create({
  template: 'my-template:v1.0.0'
})

Latest Tag

By default, templates use the latest tag:

// These are equivalent
const sandbox1 = await Sandbox.create({ template: 'my-template' })
const sandbox2 = await Sandbox.create({ template: 'my-template:latest' })

Best Practices

1. Layer Optimization

Order commands from least to most frequently changed:

# ✅ Good: System packages first (rarely change)
RUN apt-get update && apt-get install -y python3
 
# Then language packages (change occasionally)
RUN pip3 install pandas numpy
 
# Application code last (changes frequently)
COPY ./app /home/user/app

2. Caching

Use caching to speed up builds:

# Install dependencies first
COPY requirements.txt /tmp/
RUN pip3 install -r /tmp/requirements.txt
 
# Copy code after
COPY ./src /home/user/src

3. Minimize Image Size

Clean up after installations:

RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*  # Clean up

4. Use Specific Versions

# ✅ Good: Pin versions
RUN pip3 install pandas==2.0.0 numpy==1.24.0
 
# ❌ Bad: Unpinned versions
RUN pip3 install pandas numpy

Common Patterns

Multi-Language Template

FROM ubuntu:22.04
 
# Python
RUN apt-get update && apt-get install -y python3 python3-pip
 
# Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
RUN apt-get install -y nodejs
 
# Go
RUN wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
RUN tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
ENV PATH="$PATH:/usr/local/go/bin"
 
WORKDIR /home/user

Development Tools Template

FROM ubuntu:22.04
 
RUN apt-get update && apt-get install -y \
    git \
    vim \
    tmux \
    htop \
    curl \
    wget \
    jq
 
# Install development tools
RUN apt-get install -y \
    build-essential \
    gdb \
    valgrind
 
WORKDIR /home/user

Troubleshooting

Build Fails

Check build logs:

e2b template build --verbose

Template Too Large

Reduce size:

  • Remove unnecessary packages
  • Clean up after installations
  • Use smaller base images
  • Use .dockerignore to exclude files

Slow Builds

Optimize:

  • Order layers properly
  • Use build cache
  • Minimize number of layers
  • Use multi-stage builds if needed

Next Steps

Environment VariablesStreaming