Base image

How to define a base image for your template

Creating template

When creating a template, you can specify options:

JavaScript & TypeScript

const template = Template({
  fileContextPath: ".", // Custom file context path
  fileIgnorePatterns: [".git", "node_modules"], // File patterns to ignore
});

template = Template(
    file_context_path=".",  # Custom file context path
    file_ignore_patterns=[".git", "node_modules"],  # File patterns to ignore
)

File ignoring: The SDK automatically reads .dockerignore files and combines them with your fileIgnorePatterns (TypeScript) or file_ignore_patterns (Python). Files matching these patterns are excluded from uploads and hash calculations.

Defining base image

Every template starts with a base image that provides the foundation for your sandbox environment.

E2B currently supports only Debian-based images. Your base image must be Debian or a Debian derivative (e.g., debian, ubuntu, python, node). Alpine, RedHat-based, and other non-Debian distributions are not supported.

Predefined base images

Use convenience methods for common base images with Ubuntu, Debian, Python, Node.js, or Bun:

JavaScript & TypeScript

template.fromUbuntuImage("22.04"); // ubuntu:22.04
template.fromDebianImage("stable-slim"); // debian:stable-slim
template.fromPythonImage("3.13"); // python:3.13
template.fromNodeImage("lts"); // node:lts
template.fromBunImage("1.3"); // oven/bun:1.3

template.from_ubuntu_image("22.04")  # ubuntu:22.04
template.from_debian_image("stable-slim")  # debian:stable-slim
template.from_python_image("3.13")  # python:3.13
template.from_node_image("lts")  # node:lts
template.from_bun_image("1.3")  # oven/bun:1.3

Custom base image

Use any Docker image from Docker Hub or other registries:

JavaScript & TypeScript

template.fromImage("custom-image:latest");

template.from_image("custom-image:latest")

Default E2B base image

Use the default E2B base image, which comes pre-configured for sandbox environments:

JavaScript & TypeScript

template.fromBaseImage(); // e2bdev/base

template.from_base_image()  # e2bdev/base

Build from existing template

Extend an existing template from your team or organization:

JavaScript & TypeScript

template.fromTemplate("my-template"); // Your team's template
template.fromTemplate("acme/other-template"); // Full namespaced reference

template.from_template("my-template")  # Your team's template
template.from_template("acme/other-template")  # Full namespaced reference

You can only call base image methods once per template. Subsequent calls will throw an error.

Parsing existing Dockerfiles

Convert existing Dockerfiles to template format using fromDockerfile():

JavaScript & TypeScript

const dockerfileContent = `
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
WORKDIR /app
COPY . .
ENV NODE_ENV=production
ENV PORT=3000
USER appuser`;

const template = Template()
  .fromDockerfile(dockerfileContent)
  .setStartCmd("npm start", waitForTimeout(5_000));

dockerfile_content = """
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
WORKDIR /app
COPY . .
ENV NODE_ENV=production
ENV PORT=3000
USER appuser
"""

template = (
    Template()
    .from_dockerfile(dockerfile_content)
    .set_start_cmd("npm start", wait_for_timeout(5_000))
)

Dockerfile instructions support

Instruction	Supported	Behavior
FROM		Sets base image
RUN		Converts to runCmd() / run_cmd()
COPY / ADD		Converts to copy()
WORKDIR		Converts to setWorkdir() / set_workdir()
USER		Converts to setUser() / set_user()
ENV		Converts to setEnvs() / set_envs(); supports both ENV key=value and ENV key value formats
CMD / ENTRYPOINT		Converts to setStartCmd() / set_start_cmd() with 20 seconds timeout as ready command
EXPOSE		Skipped (not supported)
VOLUME		Skipped (not supported)

Multi-stage Dockerfiles are not supported.