Documentation

TemplateBase

Base class for building E2B sandbox templates.

Implements

TemplateFromImage
TemplateBuilder
TemplateFinal

Constructors

new TemplateBase(options?: TemplateOptions): TemplateBase

Parameters

Parameter	Type
`options`?	`TemplateOptions`

Returns

TemplateBase

Methods

addMcpServer()

addMcpServer(servers: keyof McpServer | keyof McpServer[]): TemplateBuilder

Install MCP servers using mcp-gateway. Note: Requires a base image with mcp-gateway pre-installed (e.g., mcp-gateway).

Parameters

Parameter	Type	Description
`servers`	keyof McpServer \| keyof McpServer[]	MCP server name(s)

Returns

TemplateBuilder

Throws

If the base template is not mcp-gateway

Example

template.addMcpServer('exa')
template.addMcpServer(['brave', 'firecrawl', 'duckduckgo'])

Implementation of

TemplateBuilder.addMcpServer

aptInstall()

aptInstall(packages: string | string[], options?: object): TemplateBuilder

Install Debian/Ubuntu packages using apt-get.

Parameters

Parameter	Type	Description
`packages`	`string` \| `string`[]	Package name(s)
`options`?	{ `fixMissing`: `boolean`; `noInstallRecommends`: `boolean`; }	-
`options.fixMissing`?	`boolean`	-
`options.noInstallRecommends`?	`boolean`	-

Returns

TemplateBuilder

Example

template.aptInstall('vim')
template.aptInstall(['git', 'curl', 'wget'])
template.aptInstall(['vim'], { noInstallRecommends: true })
template.aptInstall(['vim'], { fixMissing: true })

Implementation of

TemplateBuilder.aptInstall

betaDevContainerPrebuild()

betaDevContainerPrebuild(devcontainerDirectory: string): TemplateBuilder

Prebuild a devcontainer from the specified directory.

Parameters

Parameter	Type	Description
`devcontainerDirectory`	`string`	Path to the devcontainer directory

Returns

TemplateBuilder

Example

template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .betaDevContainerPrebuild('/my-devcontainer')

Implementation of

TemplateBuilder.betaDevContainerPrebuild

betaSetDevContainerStart()

betaSetDevContainerStart(devcontainerDirectory: string): TemplateFinal

Start a devcontainer from the specified directory.

Parameters

Parameter	Type	Description
`devcontainerDirectory`	`string`	Path to the devcontainer directory

Returns

TemplateFinal

Example

template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .startDevcontainer('/my-devcontainer')

// Prebuild and start
template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .betaDevContainerPrebuild('/my-devcontainer')
 // Other instructions...
 .betaSetDevContainerStart('/my-devcontainer')

Implementation of

TemplateBuilder.betaSetDevContainerStart

bunInstall()

bunInstall(packages?: string | string[], options?: object): TemplateBuilder

Install Bun packages using bun.

Parameters

Parameter	Type	Description
`packages`?	`string` \| `string`[]	Package name(s) or undefined for package.json
`options`?	{ `dev`: `boolean`; `g`: `boolean`; }	Install options
`options.dev`?	`boolean`	-
`options.g`?	`boolean`	-

Returns

TemplateBuilder

Example

template.bunInstall('express')
template.bunInstall(['lodash', 'axios'])
template.bunInstall('tsx', { g: true })
template.bunInstall('typescript', { dev: true })
template.bunInstall()  // Installs from package.json

Implementation of

TemplateBuilder.bunInstall

copy()

copy(
   src: PathLike | PathLike[], 
   dest: PathLike, 
   options?: object): TemplateBuilder

Copy files or directories into the template.

Parameters

Parameter	Type	Description
`src`	`PathLike` \| `PathLike`[]	Source path(s)
`dest`	`PathLike`	Destination path
`options`?	{ `forceUpload`: `true`; `mode`: `number`; `resolveSymlinks`: `boolean`; `user`: `string`; }	Copy options
`options.forceUpload`?	`true`	-
`options.mode`?	`number`	-
`options.resolveSymlinks`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.copy('requirements.txt', '/home/user/')
template.copy(['app.ts', 'config.ts'], '/app/', { mode: 0o755 })

Implementation of

TemplateBuilder.copy

copyItems()

copyItems(items: CopyItem[]): TemplateBuilder

Copy multiple items with individual options.

Parameters

Parameter	Type	Description
`items`	`CopyItem`[]	Array of copy items

Returns

TemplateBuilder

Example

template.copyItems([
  { src: 'app.ts', dest: '/app/' },
  { src: 'config.ts', dest: '/app/', mode: 0o644 }
])

Implementation of

TemplateBuilder.copyItems

fromAWSRegistry()

fromAWSRegistry(image: string, credentials: object): TemplateBuilder

Start from a Docker image in AWS ECR.

Parameters

Parameter	Type	Description
`image`	`string`	Full ECR image path
`credentials`	{ `accessKeyId`: `string`; `region`: `string`; `secretAccessKey`: `string`; }	AWS credentials
`credentials.accessKeyId`	`string`	-
`credentials.region`	`string`	-
`credentials.secretAccessKey`	`string`	-

Returns

TemplateBuilder

Example

Template().fromAWSRegistry(
  '123456789.dkr.ecr.us-west-2.amazonaws.com/myimage:latest',
  {
    accessKeyId: 'AKIA...',
    secretAccessKey: '...',
    region: 'us-west-2'
  }
)

Implementation of

TemplateFromImage.fromAWSRegistry

fromBaseImage()

fromBaseImage(): TemplateBuilder

Start from E2B’s default base image (e2bdev/base:latest).

Returns

TemplateBuilder

Example

Template().fromBaseImage()

Implementation of

TemplateFromImage.fromBaseImage

fromBunImage()

fromBunImage(variant: string): TemplateBuilder

Start from a Bun-based Docker image.

Parameters

Parameter	Type	Default value	Description
`variant`	`string`	`'latest'`	Bun variant (default: ‘latest’)

Returns

TemplateBuilder

Example

Template().fromBunImage('1.3')

Implementation of

TemplateFromImage.fromBunImage

fromDebianImage()

fromDebianImage(variant: string): TemplateBuilder

Start from a Debian-based Docker image.

Parameters

Parameter	Type	Default value	Description
`variant`	`string`	`'stable'`	Debian variant (default: ‘stable’)

Returns

TemplateBuilder

Example

Template().fromDebianImage('bookworm')

Implementation of

TemplateFromImage.fromDebianImage

fromDockerfile()

fromDockerfile(dockerfileContentOrPath: string): TemplateBuilder

Parse a Dockerfile and convert it to Template SDK format.

Parameters

Parameter	Type	Description
`dockerfileContentOrPath`	`string`	Dockerfile content or path

Returns

TemplateBuilder

Example

Template().fromDockerfile('Dockerfile')
Template().fromDockerfile('FROM python:3\nRUN pip install numpy')

Implementation of

TemplateFromImage.fromDockerfile

fromGCPRegistry()

fromGCPRegistry(image: string, credentials: object): TemplateBuilder

Start from a Docker image in Google Container Registry.

Parameters

Parameter	Type	Description
`image`	`string`	Full GCR/GAR image path
`credentials`	{ `serviceAccountJSON`: `string` \| `object`; }	GCP service account credentials
`credentials.serviceAccountJSON`	`string` \| `object`	-

Returns

TemplateBuilder

Example

Template().fromGCPRegistry(
  'gcr.io/myproject/myimage:latest',
  { serviceAccountJSON: 'path/to/service-account.json' }
)

Implementation of

TemplateFromImage.fromGCPRegistry

fromImage()

fromImage(baseImage: string, credentials?: object): TemplateBuilder

Start from a custom Docker image.

Parameters

Parameter	Type	Description
`baseImage`	`string`	Docker image name
`credentials`?	{ `password`: `string`; `username`: `string`; }	Optional credentials for private registries
`credentials.password`?	`string`	-
`credentials.username`?	`string`	-

Returns

TemplateBuilder

Example

Template().fromImage('python:3')

// With credentials (optional)
Template().fromImage('myregistry.com/myimage:latest', {
  username: 'user',
  password: 'pass'
})

Implementation of

TemplateFromImage.fromImage

fromNodeImage()

fromNodeImage(variant: string): TemplateBuilder

Start from a Node.js-based Docker image.

Parameters

Parameter	Type	Default value	Description
`variant`	`string`	`'lts'`	Node.js variant (default: ‘lts’)

Returns

TemplateBuilder

Example

Template().fromNodeImage('24')

Implementation of

TemplateFromImage.fromNodeImage

fromPythonImage()

fromPythonImage(version: string): TemplateBuilder

Start from a Python-based Docker image.

Parameters

Parameter	Type	Default value	Description
`version`	`string`	`'3'`	Python version (default: ‘3’)

Returns

TemplateBuilder

Example

Template().fromPythonImage('3')

Implementation of

TemplateFromImage.fromPythonImage

fromTemplate()

fromTemplate(template: string): TemplateBuilder

Start from an existing E2B template.

Parameters

Parameter	Type	Description
`template`	`string`	E2B template ID or alias

Returns

TemplateBuilder

Example

Template().fromTemplate('my-base-template')

Implementation of

TemplateFromImage.fromTemplate

fromUbuntuImage()

fromUbuntuImage(variant: string): TemplateBuilder

Start from an Ubuntu-based Docker image.

Parameters

Parameter	Type	Default value	Description
`variant`	`string`	`'latest'`	Ubuntu variant (default: ‘latest’)

Returns

TemplateBuilder

Example

Template().fromUbuntuImage('24.04')

Implementation of

TemplateFromImage.fromUbuntuImage

gitClone()

gitClone(
   url: string, 
   path?: PathLike, 
   options?: object): TemplateBuilder

Clone a Git repository.

Parameters

Parameter	Type	Description
`url`	`string`	Repository URL
`path`?	`PathLike`	Optional destination path
`options`?	{ `branch`: `string`; `depth`: `number`; `user`: `string`; }	Clone options
`options.branch`?	`string`	-
`options.depth`?	`number`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.gitClone('https://github.com/user/repo.git', '/app/repo')
template.gitClone('https://github.com/user/repo.git', undefined, {
  branch: 'main',
  depth: 1
})
template.gitClone('https://github.com/user/repo.git', '/app/repo', {
  user: 'root'
})

Implementation of

TemplateBuilder.gitClone

makeDir()

makeDir(path: PathLike | PathLike[], options?: object): TemplateBuilder

Create directories.

Parameters

Parameter	Type	Description
`path`	`PathLike` \| `PathLike`[]	Directory path(s)
`options`?	{ `mode`: `number`; `user`: `string`; }	Directory options
`options.mode`?	`number`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.makeDir('/app/data', { mode: 0o755 })
template.makeDir(['/app/logs', '/app/cache'])
template.makeDir('/app/data', { mode: 0o755, user: 'root' })

Implementation of

TemplateBuilder.makeDir

makeSymlink()

makeSymlink(
   src: PathLike, 
   dest: PathLike, 
   options?: object): TemplateBuilder

Create a symbolic link.

Parameters

Parameter	Type	Description
`src`	`PathLike`	Source path (target)
`dest`	`PathLike`	Destination path (symlink location)
`options`?	{ `force`: `boolean`; `user`: `string`; }	Symlink options
`options.force`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.makeSymlink('/usr/bin/python3', '/usr/bin/python')
template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { user: 'root' })
template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { force: true })

Implementation of

TemplateBuilder.makeSymlink

npmInstall()

npmInstall(packages?: string | string[], options?: object): TemplateBuilder

Install Node.js packages using npm.

Parameters

Parameter	Type	Description
`packages`?	`string` \| `string`[]	Package name(s) or undefined for package.json
`options`?	{ `dev`: `boolean`; `g`: `boolean`; }	Install options
`options.dev`?	`boolean`	-
`options.g`?	`boolean`	-

Returns

TemplateBuilder

Example

template.npmInstall('express')
template.npmInstall(['lodash', 'axios'])
template.npmInstall('tsx', { g: true })
template.npmInstall('typescript', { dev: true })
template.npmInstall()  // Installs from package.json

Implementation of

TemplateBuilder.npmInstall

pipInstall()

pipInstall(packages?: string | string[], options?: object): TemplateBuilder

Install Python packages using pip.

Parameters

Parameter	Type	Description
`packages`?	`string` \| `string`[]	Package name(s) or undefined for current directory
`options`?	{ `g`: `boolean`; }	Install options
`options.g`?	`boolean`	Install globally as root (default: true). Set to false for user-only installation with —user flag

Returns

TemplateBuilder

Example

template.pipInstall('numpy')  // Installs globally (default)
template.pipInstall(['pandas', 'scikit-learn'])
template.pipInstall('numpy', { g: false })  // Install for user only
template.pipInstall()  // Installs from current directory

Implementation of

TemplateBuilder.pipInstall

remove()

remove(path: PathLike | PathLike[], options?: object): TemplateBuilder

Remove files or directories.

Parameters

Parameter	Type	Description
`path`	`PathLike` \| `PathLike`[]	Path(s) to remove
`options`?	{ `force`: `boolean`; `recursive`: `boolean`; `user`: `string`; }	Remove options
`options.force`?	`boolean`	-
`options.recursive`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.remove('/tmp/cache', { recursive: true, force: true })
template.remove('/tmp/cache', { recursive: true, force: true, user: 'root' })

Implementation of

TemplateBuilder.remove

rename()

rename(
   src: PathLike, 
   dest: PathLike, 
   options?: object): TemplateBuilder

Rename or move a file or directory.

Parameters

Parameter	Type	Description
`src`	`PathLike`	Source path
`dest`	`PathLike`	Destination path
`options`?	{ `force`: `boolean`; `user`: `string`; }	Rename options
`options.force`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.rename('/tmp/old.txt', '/tmp/new.txt')
template.rename('/tmp/old.txt', '/tmp/new.txt', { user: 'root' })

Implementation of

TemplateBuilder.rename

runCmd()

Call Signature

runCmd(command: string, options?: object): TemplateBuilder

Run a shell command.

Parameters

Parameter	Type	Description
`command`	`string`	Command string
`options`?	{ `user`: `string`; }	Command options
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.runCmd('apt-get update')
template.runCmd(['pip install numpy', 'pip install pandas'])
template.runCmd('apt-get install vim', { user: 'root' })

Implementation of

TemplateBuilder.runCmd

Call Signature

runCmd(commands: string[], options?: object): TemplateBuilder

Run multiple shell commands.

Parameters

Parameter	Type	Description
`commands`	`string`[]	Array of command strings
`options`?	{ `user`: `string`; }	Command options
`options.user`?	`string`	-

Returns

TemplateBuilder

Implementation of

TemplateBuilder.runCmd

setEnvs()

setEnvs(envs: Record<string, string>): TemplateBuilder

Set environment variables. Note: Environment variables defined here are available only during template build.

Parameters

Parameter	Type	Description
`envs`	`Record`<`string`, `string`>	Environment variables

Returns

TemplateBuilder

Example

template.setEnvs({ NODE_ENV: 'production', PORT: '8080' })

Implementation of

TemplateBuilder.setEnvs

setReadyCmd()

setReadyCmd(readyCommand: string | ReadyCmd): TemplateFinal

Set or update the ready check command.

Parameters

Parameter	Type	Description
`readyCommand`	`string` \| `ReadyCmd`	Command to check readiness

Returns

TemplateFinal

Example

// Using a string command
template.setReadyCmd('curl http://localhost:8000/health')

// Using ReadyCmd helpers
import { waitForPort, waitForFile, waitForProcess } from 'e2b'

template.setReadyCmd(waitForPort(3000))

template.setReadyCmd(waitForFile('/tmp/ready'))

template.setReadyCmd(waitForProcess('nginx'))

Implementation of

TemplateBuilder.setReadyCmd

setStartCmd()

setStartCmd(startCommand: string, readyCommand: string | ReadyCmd): TemplateFinal

Set the start command and ready check.

Parameters

Parameter	Type	Description
`startCommand`	`string`	Command to run on startup
`readyCommand`	`string` \| `ReadyCmd`	Command to check readiness

Returns

TemplateFinal

Example

// Using a string command
template.setStartCmd(
  'node app.js',
  'curl http://localhost:8000/health'
)

// Using ReadyCmd helpers
import { waitForPort, waitForURL } from 'e2b'

template.setStartCmd(
  'python -m http.server 8000',
  waitForPort(8000)
)

template.setStartCmd(
  'npm start',
  waitForURL('http://localhost:3000/health', 200)
)

Implementation of

TemplateBuilder.setStartCmd

setUser()

setUser(user: string): TemplateBuilder

Set the user for subsequent commands.

Parameters

Parameter	Type	Description
`user`	`string`	Username

Returns

TemplateBuilder

Example

template.setUser('root')

Implementation of

TemplateBuilder.setUser

setWorkdir()

setWorkdir(workdir: PathLike): TemplateBuilder

Set the working directory.

Parameters

Parameter	Type	Description
`workdir`	`PathLike`	Working directory path

Returns

TemplateBuilder

Example

template.setWorkdir('/app')

Implementation of

TemplateBuilder.setWorkdir

skipCache()

skipCache(): this

Skip cache for all subsequent build instructions from this point.

Returns

this

Example

Template().skipCache().fromPythonImage('3')

Implementation of

TemplateBuilder.skipCache

aliasExists()

static aliasExists(alias: string, options?: ConnectionOpts): Promise<boolean>

Check if a template with the given alias exists.

Parameters

Parameter	Type	Description
`alias`	`string`	Template alias to check
`options`?	`ConnectionOpts`	Authentication options

Returns

Promise<boolean> True if the alias exists, false otherwise

Deprecated

Use exists instead.

Example

const exists = await Template.aliasExists('my-python-env')
if (exists) {
  console.log('Template exists!')
}

assignTags()

static assignTags(
   targetName: string, 
   tags: string | string[], 
options?: ConnectionOpts): Promise<TemplateTagInfo>

Assign tag(s) to an existing template build.

Parameters

Parameter	Type	Description
`targetName`	`string`	Template name in ‘name:tag’ format (the source build to tag from)
`tags`	`string` \| `string`[]	Tag or tags to assign
`options`?	`ConnectionOpts`	Authentication options

Returns

Promise<TemplateTagInfo> Tag info with buildId and assigned tags

Example

// Assign a single tag
await Template.assignTags('my-template:v1.0', 'production')

// Assign multiple tags
await Template.assignTags('my-template:v1.0', ['production', 'stable'])

build()

Call Signature

static build(
   template: TemplateClass, 
   name: string, 
options?: Omit<BuildOptions, "alias">): Promise<BuildInfo>

Build and deploy a template to E2B infrastructure.

Parameters

Parameter	Type	Description
`template`	`TemplateClass`	The template to build
`name`	`string`	Template name in ‘name’ or ‘name:tag’ format
`options`?	`Omit`<`BuildOptions`, `"alias"`>	Optional build configuration options

Returns

Promise<BuildInfo>

Example

const template = Template().fromPythonImage('3')

// Build with single tag in name
await Template.build(template, 'my-python-env:v1.0')

// Build with multiple tags
await Template.build(template, 'my-python-env', { tags: ['v1.0', 'stable'] })

Call Signature

static build(template: TemplateClass, options: BuildOptions): Promise<BuildInfo>

Build and deploy a template to E2B infrastructure.

Parameters

Parameter	Type	Description
`template`	`TemplateClass`	The template to build
`options`	`BuildOptions`	Build configuration options with alias (deprecated)

Returns

Promise<BuildInfo>

Deprecated

Use the overload with name parameter instead.

Example

// Deprecated:
await Template.build(template, { alias: 'my-python-env' })

// Use instead:
await Template.build(template, 'my-python-env:v1.0')

buildInBackground()

Call Signature

static buildInBackground(
   template: TemplateClass, 
   name: string, 
options?: Omit<BuildOptions, "alias">): Promise<BuildInfo>

Build and deploy a template to E2B infrastructure without waiting for completion.

Parameters

Parameter	Type	Description
`template`	`TemplateClass`	The template to build
`name`	`string`	Template name in ‘name’ or ‘name:tag’ format
`options`?	`Omit`<`BuildOptions`, `"alias"`>	Optional build configuration options

Returns

Promise<BuildInfo>

Example

const template = Template().fromPythonImage('3')

// Build with single tag in name
const data = await Template.buildInBackground(template, 'my-python-env:v1.0')

// Build with multiple tags
const data = await Template.buildInBackground(template, 'my-python-env', { tags: ['v1.0', 'stable'] })

Call Signature

static buildInBackground(template: TemplateClass, options: BuildOptions): Promise<BuildInfo>

Build and deploy a template to E2B infrastructure without waiting for completion.

Parameters

Parameter	Type	Description
`template`	`TemplateClass`	The template to build
`options`	`BuildOptions`	Build configuration options with alias (deprecated)

Returns

Promise<BuildInfo>

Deprecated

Use the overload with name parameter instead.

Example

// Deprecated:
await Template.buildInBackground(template, { alias: 'my-python-env' })

// Use instead:
await Template.buildInBackground(template, 'my-python-env:v1.0')

exists()

static exists(name: string, options?: ConnectionOpts): Promise<boolean>

Check if a template with the given name exists.

Parameters

Parameter	Type	Description
`name`	`string`	Template name to check
`options`?	`ConnectionOpts`	Authentication options

Returns

Promise<boolean> True if the name exists, false otherwise

Example

const exists = await Template.exists('my-python-env')
if (exists) {
  console.log('Template exists!')
}

getBuildStatus()

static getBuildStatus(data: Pick<BuildInfo, "buildId" | "templateId">, options?: GetBuildStatusOptions): Promise<TemplateBuildStatusResponse>

Get the status of a build.

Parameters

Parameter	Type	Description
`data`	`Pick`<`BuildInfo`, `"buildId"` \| `"templateId"`>	Build identifiers
`options`?	`GetBuildStatusOptions`	Authentication options

Returns

Promise<TemplateBuildStatusResponse>

Example

const status = await Template.getBuildStatus(data, { logsOffset: 0 })

getTags()

static getTags(templateId: string, options?: ConnectionOpts): Promise<TemplateTag[]>

Get all tags for a template.

Parameters

Parameter	Type	Description
`templateId`	`string`	Template ID or name
`options`?	`ConnectionOpts`	Authentication options

Returns

Promise<TemplateTag[]> Array of tag details including tag name, buildId, and creation date

Example

const tags = await Template.getTags('my-template')
for (const tag of tags) {
  console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`)
}

removeTags()

static removeTags(
   name: string, 
   tags: string | string[], 
options?: ConnectionOpts): Promise<void>

Remove tag(s) from a template.

Parameters

Parameter	Type	Description
`name`	`string`	Template name
`tags`	`string` \| `string`[]	Tag or tags to remove
`options`?	`ConnectionOpts`	Authentication options

Returns

Promise<void>

Example

// Remove a single tag
await Template.removeTags('my-template', 'production')

// Remove multiple tags from a template
await Template.removeTags('my-template', ['production', 'staging'])

toDockerfile()

static toDockerfile(template: TemplateClass): string

Convert a template to Dockerfile format. Note: Templates based on other E2B templates cannot be converted to Dockerfile.

Parameters

Parameter	Type	Description
`template`	`TemplateClass`	The template to convert

Returns

string Dockerfile string representation

Throws

Error if the template is based on another E2B template

toJSON()

static toJSON(template: TemplateClass, computeHashes: boolean): Promise<string>

Convert a template to JSON representation.

Parameters

Parameter	Type	Default value	Description
`template`	`TemplateClass`	`undefined`	The template to convert
`computeHashes`	`boolean`	`true`	Whether to compute file hashes for cache invalidation

Returns

Promise<string> JSON string representation of the template

Interfaces

TemplateBuilder

Main builder state for constructing templates. Provides methods for customizing the template environment.

Methods

addMcpServer()

addMcpServer(servers: keyof McpServer | keyof McpServer[]): TemplateBuilder

Install MCP servers using mcp-gateway. Note: Requires a base image with mcp-gateway pre-installed (e.g., mcp-gateway).

Parameters

Parameter	Type	Description
`servers`	keyof McpServer \| keyof McpServer[]	MCP server name(s)

Returns

TemplateBuilder

Throws

If the base template is not mcp-gateway

Example

template.addMcpServer('exa')
template.addMcpServer(['brave', 'firecrawl', 'duckduckgo'])

aptInstall()

aptInstall(packages: string | string[], options?: object): TemplateBuilder

Install Debian/Ubuntu packages using apt-get.

Parameters

Parameter	Type	Description
`packages`	`string` \| `string`[]	Package name(s)
`options`?	{ `fixMissing`: `boolean`; `noInstallRecommends`: `boolean`; }	-
`options.fixMissing`?	`boolean`	-
`options.noInstallRecommends`?	`boolean`	-

Returns

TemplateBuilder

Example

template.aptInstall('vim')
template.aptInstall(['git', 'curl', 'wget'])
template.aptInstall(['vim'], { noInstallRecommends: true })
template.aptInstall(['vim'], { fixMissing: true })

betaDevContainerPrebuild()

betaDevContainerPrebuild(devcontainerDirectory: string): TemplateBuilder

Prebuild a devcontainer from the specified directory.

Parameters

Parameter	Type	Description
`devcontainerDirectory`	`string`	Path to the devcontainer directory

Returns

TemplateBuilder

Example

template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .betaDevContainerPrebuild('/my-devcontainer')

betaSetDevContainerStart()

betaSetDevContainerStart(devcontainerDirectory: string): TemplateFinal

Start a devcontainer from the specified directory.

Parameters

Parameter	Type	Description
`devcontainerDirectory`	`string`	Path to the devcontainer directory

Returns

TemplateFinal

Example

template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .startDevcontainer('/my-devcontainer')

// Prebuild and start
template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .betaDevContainerPrebuild('/my-devcontainer')
 // Other instructions...
 .betaSetDevContainerStart('/my-devcontainer')

bunInstall()

bunInstall(packages?: string | string[], options?: object): TemplateBuilder

Install Bun packages using bun.

Parameters

Parameter	Type	Description
`packages`?	`string` \| `string`[]	Package name(s) or undefined for package.json
`options`?	{ `dev`: `boolean`; `g`: `boolean`; }	Install options
`options.dev`?	`boolean`	-
`options.g`?	`boolean`	-

Returns

TemplateBuilder

Example

template.bunInstall('express')
template.bunInstall(['lodash', 'axios'])
template.bunInstall('tsx', { g: true })
template.bunInstall('typescript', { dev: true })
template.bunInstall()  // Installs from package.json

copy()

copy(
   src: PathLike | PathLike[], 
   dest: PathLike, 
   options?: object): TemplateBuilder

Copy files or directories into the template.

Parameters

Parameter	Type	Description
`src`	`PathLike` \| `PathLike`[]	Source path(s)
`dest`	`PathLike`	Destination path
`options`?	{ `forceUpload`: `true`; `mode`: `number`; `resolveSymlinks`: `boolean`; `user`: `string`; }	Copy options
`options.forceUpload`?	`true`	-
`options.mode`?	`number`	-
`options.resolveSymlinks`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.copy('requirements.txt', '/home/user/')
template.copy(['app.ts', 'config.ts'], '/app/', { mode: 0o755 })

copyItems()

copyItems(items: CopyItem[]): TemplateBuilder

Copy multiple items with individual options.

Parameters

Parameter	Type	Description
`items`	`CopyItem`[]	Array of copy items

Returns

TemplateBuilder

Example

template.copyItems([
  { src: 'app.ts', dest: '/app/' },
  { src: 'config.ts', dest: '/app/', mode: 0o644 }
])

gitClone()

gitClone(
   url: string, 
   path?: PathLike, 
   options?: object): TemplateBuilder

Clone a Git repository.

Parameters

Parameter	Type	Description
`url`	`string`	Repository URL
`path`?	`PathLike`	Optional destination path
`options`?	{ `branch`: `string`; `depth`: `number`; `user`: `string`; }	Clone options
`options.branch`?	`string`	-
`options.depth`?	`number`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.gitClone('https://github.com/user/repo.git', '/app/repo')
template.gitClone('https://github.com/user/repo.git', undefined, {
  branch: 'main',
  depth: 1
})
template.gitClone('https://github.com/user/repo.git', '/app/repo', {
  user: 'root'
})

makeDir()

makeDir(path: PathLike | PathLike[], options?: object): TemplateBuilder

Create directories.

Parameters

Parameter	Type	Description
`path`	`PathLike` \| `PathLike`[]	Directory path(s)
`options`?	{ `mode`: `number`; `user`: `string`; }	Directory options
`options.mode`?	`number`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.makeDir('/app/data', { mode: 0o755 })
template.makeDir(['/app/logs', '/app/cache'])
template.makeDir('/app/data', { mode: 0o755, user: 'root' })

makeSymlink()

makeSymlink(
   src: PathLike, 
   dest: PathLike, 
   options?: object): TemplateBuilder

Create a symbolic link.

Parameters

Parameter	Type	Description
`src`	`PathLike`	Source path (target)
`dest`	`PathLike`	Destination path (symlink location)
`options`?	{ `force`: `boolean`; `user`: `string`; }	Symlink options
`options.force`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.makeSymlink('/usr/bin/python3', '/usr/bin/python')
template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { user: 'root' })
template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { force: true })

npmInstall()

npmInstall(packages?: string | string[], options?: object): TemplateBuilder

Install Node.js packages using npm.

Parameters

Parameter	Type	Description
`packages`?	`string` \| `string`[]	Package name(s) or undefined for package.json
`options`?	{ `dev`: `boolean`; `g`: `boolean`; }	Install options
`options.dev`?	`boolean`	-
`options.g`?	`boolean`	-

Returns

TemplateBuilder

Example

template.npmInstall('express')
template.npmInstall(['lodash', 'axios'])
template.npmInstall('tsx', { g: true })
template.npmInstall('typescript', { dev: true })
template.npmInstall()  // Installs from package.json

pipInstall()

pipInstall(packages?: string | string[], options?: object): TemplateBuilder

Install Python packages using pip.

Parameters

Parameter	Type	Description
`packages`?	`string` \| `string`[]	Package name(s) or undefined for current directory
`options`?	{ `g`: `boolean`; }	Install options
`options.g`?	`boolean`	Install globally as root (default: true). Set to false for user-only installation with —user flag

Returns

TemplateBuilder

Example

template.pipInstall('numpy')  // Installs globally (default)
template.pipInstall(['pandas', 'scikit-learn'])
template.pipInstall('numpy', { g: false })  // Install for user only
template.pipInstall()  // Installs from current directory

remove()

remove(path: PathLike | PathLike[], options?: object): TemplateBuilder

Remove files or directories.

Parameters

Parameter	Type	Description
`path`	`PathLike` \| `PathLike`[]	Path(s) to remove
`options`?	{ `force`: `boolean`; `recursive`: `boolean`; `user`: `string`; }	Remove options
`options.force`?	`boolean`	-
`options.recursive`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.remove('/tmp/cache', { recursive: true, force: true })
template.remove('/tmp/cache', { recursive: true, force: true, user: 'root' })

rename()

rename(
   src: PathLike, 
   dest: PathLike, 
   options?: object): TemplateBuilder

Rename or move a file or directory.

Parameters

Parameter	Type	Description
`src`	`PathLike`	Source path
`dest`	`PathLike`	Destination path
`options`?	{ `force`: `boolean`; `user`: `string`; }	Rename options
`options.force`?	`boolean`	-
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.rename('/tmp/old.txt', '/tmp/new.txt')
template.rename('/tmp/old.txt', '/tmp/new.txt', { user: 'root' })

runCmd()

Call Signature

runCmd(command: string, options?: object): TemplateBuilder

Run a shell command.

Parameters

Parameter	Type	Description
`command`	`string`	Command string
`options`?	{ `user`: `string`; }	Command options
`options.user`?	`string`	-

Returns

TemplateBuilder

Example

template.runCmd('apt-get update')
template.runCmd(['pip install numpy', 'pip install pandas'])
template.runCmd('apt-get install vim', { user: 'root' })

Call Signature

runCmd(commands: string[], options?: object): TemplateBuilder

Run multiple shell commands.

Parameters

Parameter	Type	Description
`commands`	`string`[]	Array of command strings
`options`?	{ `user`: `string`; }	Command options
`options.user`?	`string`	-

Returns

TemplateBuilder

Call Signature

runCmd(commandOrCommands: string | string[], options?: object): TemplateBuilder

Run command(s).

Parameters

Parameter	Type	Description
`commandOrCommands`	`string` \| `string`[]	Command or commands
`options`?	{ `user`: `string`; }	Command options
`options.user`?	`string`	-

Returns

TemplateBuilder

setEnvs()

setEnvs(envs: Record<string, string>): TemplateBuilder

Set environment variables. Note: Environment variables defined here are available only during template build.

Parameters

Parameter	Type	Description
`envs`	`Record`<`string`, `string`>	Environment variables

Returns

TemplateBuilder

Example

template.setEnvs({ NODE_ENV: 'production', PORT: '8080' })

setReadyCmd()

setReadyCmd(readyCommand: string | ReadyCmd): TemplateFinal

Set or update the ready check command.

Parameters

Parameter	Type	Description
`readyCommand`	`string` \| `ReadyCmd`	Command to check readiness

Returns

TemplateFinal

Example

// Using a string command
template.setReadyCmd('curl http://localhost:8000/health')

// Using ReadyCmd helpers
import { waitForPort, waitForFile, waitForProcess } from 'e2b'

template.setReadyCmd(waitForPort(3000))

template.setReadyCmd(waitForFile('/tmp/ready'))

template.setReadyCmd(waitForProcess('nginx'))

setStartCmd()

setStartCmd(startCommand: string, readyCommand: string | ReadyCmd): TemplateFinal

Set the start command and ready check.

Parameters

Parameter	Type	Description
`startCommand`	`string`	Command to run on startup
`readyCommand`	`string` \| `ReadyCmd`	Command to check readiness

Returns

TemplateFinal

Example

// Using a string command
template.setStartCmd(
  'node app.js',
  'curl http://localhost:8000/health'
)

// Using ReadyCmd helpers
import { waitForPort, waitForURL } from 'e2b'

template.setStartCmd(
  'python -m http.server 8000',
  waitForPort(8000)
)

template.setStartCmd(
  'npm start',
  waitForURL('http://localhost:3000/health', 200)
)

setUser()

setUser(user: string): TemplateBuilder

Set the user for subsequent commands.

Parameters

Parameter	Type	Description
`user`	`string`	Username

Returns

TemplateBuilder

Example

template.setUser('root')

setWorkdir()

setWorkdir(workdir: PathLike): TemplateBuilder

Set the working directory.

Parameters

Parameter	Type	Description
`workdir`	`PathLike`	Working directory path

Returns

TemplateBuilder

Example

template.setWorkdir('/app')

skipCache()

skipCache(): this

Skip cache for all subsequent build instructions from this point.

Returns

this

Example

template.skipCache().runCmd('apt-get update')

Type Aliases

BuildInfo

type BuildInfo = object;

Information about a built template.

Type declaration

Name	Type	Description
`alias`	`string`	First alias from the build (for backward compatibility). Deprecated Use `name` instead.
`buildId`	`string`	Build identifier.
`name`	`string`	Name of the template.
`tags`	`string`[]	Tags assigned to this build.
`templateId`	`string`	Template identifier.

BuildOptions

type BuildOptions = ConnectionOpts & BasicBuildOptions;

Options for building a template with authentication.

BuildStatusReason

type BuildStatusReason = object;

Reason for the current build status (typically for errors).

Type declaration

Name	Type	Description
`logEntries`	`LogEntry`[]	Log entries related to the status reason.
`message`	`string`	Message with the status reason.
`step`?	`string`	Step that failed.

CopyItem

type CopyItem = object;

Configuration for a single file/directory copy operation.

Type declaration

Name	Type
`dest`	`PathLike`
`forceUpload`?	`true`
`mode`?	`number`
`resolveSymlinks`?	`boolean`
`src`	`PathLike` \| `PathLike`[]
`user`?	`string`

GetBuildStatusOptions

type GetBuildStatusOptions = ConnectionOpts & object;

Options for getting build status.

Type declaration

Name	Type
`logsOffset`?	`number`

McpServerName

type McpServerName = keyof McpServer;

MCP server names that can be installed.

TemplateBuildStatus

type TemplateBuildStatus = "building" | "waiting" | "ready" | "error";

Status of a template build.

TemplateBuildStatusResponse

type TemplateBuildStatusResponse = object;

Response from getting build status.

Type declaration

Name	Type	Description
`buildID`	`string`	Build identifier.
`logEntries`	`LogEntry`[]	Build log entries.
`logs`	`string`[]	Build logs (raw strings). Deprecated Use `logEntries` instead.
`reason`?	`BuildStatusReason`	Reason for the current status (typically for errors).
`status`	`TemplateBuildStatus`	Current status of the build.
`templateID`	`string`	Template identifier.

TemplateClass

type TemplateClass = TemplateBuilder | TemplateFinal;

Type representing a template in any state (builder or final).

TemplateTag

type TemplateTag = object;

Detailed information about a single template tag.

Type declaration

Name	Type	Description
`buildId`	`string`	Build identifier associated with this tag.
`createdAt`	`Date`	When this tag was assigned.
`tag`	`string`	Name of the tag.

TemplateTagInfo

type TemplateTagInfo = object;

Information about assigned template tags.

Type declaration

Name	Type	Description
`buildId`	`string`	Build identifier associated with this tag.
`tags`	`string`[]	Assigned tags of the template.

Functions

Template()

function Template(options?: TemplateOptions): TemplateFromImage

Create a new E2B template builder instance.

Parameters

Parameter	Type	Description
`options`?	`TemplateOptions`	Optional configuration for the template builder

Returns

TemplateFromImage A new template builder instance

Example

import { Template } from 'e2b'

const template = Template()
  .fromPythonImage('3')
  .copy('requirements.txt', '/app/')
  .pipInstall()

await Template.build(template, 'my-python-app:v1.0')

​TemplateBase

​Implements

​Constructors

Parameters

Returns

​Methods

​addMcpServer()

Parameters

Returns

Throws

Example

Implementation of

​aptInstall()

Parameters

Returns

Example

Implementation of

​betaDevContainerPrebuild()

Parameters

Returns

Example

Implementation of

​betaSetDevContainerStart()

Parameters

Returns

Example

Implementation of

​bunInstall()

Parameters

Returns

Example

Implementation of

​copy()

Parameters

Returns

Example

Implementation of

​copyItems()

Parameters

Returns

Example

Implementation of

​fromAWSRegistry()

Parameters

Returns

Example

Implementation of

​fromBaseImage()

Returns

Example

Implementation of

​fromBunImage()

Parameters

Returns

Example

Implementation of

​fromDebianImage()

Parameters

Returns

Example

Implementation of

​fromDockerfile()

Parameters

Returns

Example

Implementation of

​fromGCPRegistry()

Parameters

Returns

Example

Implementation of

​fromImage()

Parameters

Returns

Example

Implementation of

​fromNodeImage()

Parameters

Returns

Example

TemplateBase

Implements

Constructors

Methods

addMcpServer()

aptInstall()

betaDevContainerPrebuild()

betaSetDevContainerStart()

bunInstall()

copy()

copyItems()

fromAWSRegistry()

fromBaseImage()

fromBunImage()

fromDebianImage()

fromDockerfile()

fromGCPRegistry()

fromImage()

fromNodeImage()

fromPythonImage()

fromTemplate()

fromUbuntuImage()

gitClone()

makeDir()

makeSymlink()

npmInstall()

pipInstall()

remove()

rename()

runCmd()

setEnvs()

setReadyCmd()