Template – E2B Docs

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, "templateId" | "buildId">, options?: GetBuildStatusOptions): Promise<TemplateBuildStatusResponse>

Get the status of a build.

Parameters

Parameter	Type	Description
`data`	`Pick`<`BuildInfo`, `"templateId"` \| `"buildId"`>	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)

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')