Sandbox Templates

Sandbox templates allow you to create preconfigured sandbox environments with custom base images, dependencies, files, and startup commands. Using templates can significantly reduce startup time.

What is a Template

A template is a pre-built sandbox environment that includes:

• Base image: Ubuntu, Debian, Python, Node.js, etc.
• Dependencies: Pre-installed system and language packages
• File system: Pre-copied files and configurations
• Environment variables: Variables set at build time
• Startup command: Processes that run automatically when the sandbox starts

Benefits

• Fast startup: Starts in a few hundred milliseconds
• Pre-running processes: Servers, databases, etc., are already running
• Consistency: All instances use the same configuration

Creating a Template

Use the SDK's Builder pattern to define and build a template:

import { Template, waitForPort } from '@e2b/code-interpreter'

// Define the template using the Builder pattern
const template = Template()
  .fromPythonImage('3.11')
  .setEnvs({ ENV: 'production' })
  .setWorkdir('/app')
  .pipInstall(['numpy', 'pandas'])
  .setStartCmd('python server.py', waitForPort(8000))

// Build and deploy the template
const buildInfo = await Template.build(template, {
  alias: 'my-python-env',
  cpuCount: 2,
  memoryMB: 1024
})

console.log('Template ID:', buildInfo.templateId)

Note: Methods like fromBaseImage() and fromPythonImage() pull official images from Docker Hub by default, which may fail in certain network environments (e.g., timeouts, Connection reset).

Recommended approach: Pull official images directly through our image proxy and use the full image path in the template:

.fromImage("<proxy-address>/<registry-address>/<image>")

Note: The registry address for Docker Hub is registry-1.docker.io, not docker.io.

For example, to pull the python:3.11 image from Docker Hub:

.fromImage("crp-internal.sufycs.com/registry-1.docker.io/library/python:3.11")

For production environments, it is recommended to use a fixed minor version (e.g., python:3.11) or a digest to pin the image, ensuring reproducible builds.

Currently supported registry services with proxy:

• registry-1.docker.io
• quay.io
• ghcr.io
• gcr.io

Template Naming

Assign clear, descriptive aliases to templates. It is recommended to use a business prefix:

• Business prefix + application name: mycompany-app
• Business prefix + application name + environment: mycompany-app-production, mycompany-app-staging

Note: Template aliases are globally unique. Use a business prefix to ensure uniqueness.

Using a Template

After building, create a sandbox using the template alias:

import { Sandbox } from '@e2b/code-interpreter'

const sandbox = await Sandbox.create({
  template: 'my-python-env'
})