Documentation

Creating template

When creating a template, you can specify options:

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 identifies the image’s distribution from its /etc/os-release. Supported: Debian/Ubuntu, Fedora and the RHEL family (including Rocky Linux and AlmaLinux), Arch, and Alpine. Not supported:

Images with no identifiable distribution (no /etc/os-release), such as scratch, distroless, or pure nixos/nix.
Minimal images missing required packages, such as RHEL UBI-minimal with restricted repositories.

Unsupported images fail the build with a clear error naming the reason.

For NixOS, use the official e2bdev/nixos image instead of a raw NixOS image.

Predefined base images

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

template.fromUbuntuImage("22.04"); // ubuntu:22.04
template.fromDebianImage("stable-slim"); // debian:stable-slim
template.fromFedoraImage("44"); // fedora:44
template.fromAlpineImage("3.24"); // alpine:3.24
template.fromArchImage("base-devel"); // archlinux:base-devel
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_fedora_image("44")  # fedora:44
template.from_alpine_image("3.24")  # alpine:3.24
template.from_arch_image("base-devel")  # archlinux:base-devel
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:

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:

template.fromBaseImage(); // e2bdev/base

template.from_base_image()  # e2bdev/base

base is also the template used when you call Sandbox.create() without specifying one. It is Debian-based and comes with common tooling pre-installed: Python 3, Node.js, Yarn, git, curl, build-essential, and the GitHub CLI (gh). For the exact contents, see the public Dockerfile: templates/base/e2b.Dockerfile.

NixOS base image

Arbitrary NixOS images (such as nixos/nix) aren’t supported directly, because they don’t expose the /etc/os-release metadata E2B needs to identify the distribution. To build NixOS-based sandboxes, use the official e2bdev/nixos image, which E2B prepares to work with the sandbox environment:

template.fromImage("e2bdev/nixos");

template.from_image("e2bdev/nixos")

Default resources

A sandbox gets its CPU and memory from the template it’s built on. A sandbox built from base starts with 2 vCPU and 512 MiB of RAM. You can override CPU and memory when you build a template (cpuCount/cpu_count, memoryMB/memory_mb). Disk size is not a default you set per sandbox; it’s determined by your project’s tier limit and applied at build time (see Build limits).

Build from existing template

Extend an existing template from your project or organization:

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

template.from_template("my-template")  # Your project'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():

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.

Getting started

Use cases

Agents

Storage

Code interpreting

Sandbox

Templates

Network

Filesystem

Volumes

Commands

MCP gateway

CLI

Deployment

Migration

FAQ

Base image

Creating template

Defining base image

Predefined base images

Custom base image

Default E2B base image

NixOS base image

Default resources

Build from existing template

Parsing existing Dockerfiles

Dockerfile instructions support

​Creating template

​Defining base image

​Predefined base images

​Custom base image

​Default E2B base image

​NixOS base image

​Default resources

​Build from existing template

​Parsing existing Dockerfiles

​Dockerfile instructions support

Creating template

Defining base image

Predefined base images

Custom base image

Default E2B base image

NixOS base image

Default resources

Build from existing template

Parsing existing Dockerfiles

Dockerfile instructions support