Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
import type { PathLike } from 'node:fs'
import { ApiClient } from '../api'
import {
ClientFactory,
ConnectionConfig,
ConnectionOpts,
} from '../connectionConfig'
import { BuildError, InvalidArgumentError } from '../errors'
import { runtime, shellQuote } from '../utils'
import { callableTemplate } from './callable'
import {
assignTags,
checkAliasExists,
getTemplateTags,
removeTags,
getBuildStatus,
getFileUploadLink,
requestBuild,
triggerBuild,
TriggerBuildTemplate,
uploadFile,
waitForBuildFinish,
} from './buildApi'
import { GZIP, RESOLVE_SYMLINKS } from './consts'
import { parseDockerfile } from './dockerfileParser'
import { LogEntry, LogEntryEnd, LogEntryStart } from './logger'
import { ReadyCmd, waitForFile } from './readycmd'
import {
BuildInfo,
BuildOptions,
CopyItem,
GetBuildStatusOptions,
Instruction,
InstructionType,
McpServerName,
RegistryConfig,
TemplateBuilder,
TemplateBuildStatusResponse,
TemplateClass,
TemplateFinal,
TemplateFromImage,
TemplateOptions,
TemplateTag,
TemplateTagInfo,
} from './types'
import {
calculateFilesHash,
getCallerDirectory,
getCallerFrame,
normalizeBuildArguments,
padOctal,
readDockerignore,
readGCPServiceAccountJSON,
validateRelativePath,
} from './utils'
/**
* Builder for E2B sandbox templates, and the entrypoint for the template API.
*
* Exposed as {@link Template}, which can be called as a factory.
*/
export class TemplateBase
extends ClientFactory
implements TemplateFromImage, TemplateBuilder, TemplateFinal
{
private defaultBaseImage: string = 'e2bdev/base'
private baseImage: string | undefined = this.defaultBaseImage
private baseTemplate: string | undefined = undefined
private registryConfig: RegistryConfig | undefined = undefined
private startCmd: string | undefined = undefined
private readyCmd: string | undefined = undefined
// Force the whole template to be rebuilt
private force: boolean = false
// Force the next layer to be rebuilt
private forceNextLayer: boolean = false
private instructions: Instruction[] = []
private fileContextPath: PathLike
private fileIgnorePatterns: string[] = []
private logsRefreshFrequency: number = 200
private stackTraces: (string | undefined)[] = []
constructor(options?: TemplateOptions) {
super()
this.fileContextPath =
options?.fileContextPath ??
(runtime === 'browser' ? '.' : (getCallerDirectory() ?? '.'))
this.fileIgnorePatterns =
options?.fileIgnorePatterns ?? this.fileIgnorePatterns
}
/**
* Convert a template to JSON representation.
*
* @param template The template to convert
* @param computeHashes Whether to compute file hashes for cache invalidation
* @returns JSON string representation of the template
*/
static toJSON(
template: TemplateClass,
computeHashes: boolean = true
): Promise<string> {
return (template as TemplateBase).toJSON(computeHashes)
}
/**
* Convert a template to Dockerfile format.
* Note: Templates based on other E2B templates cannot be converted to Dockerfile.
*
* @param template The template to convert
* @returns Dockerfile string representation
* @throws Error if the template is based on another E2B template
*/
static toDockerfile(template: TemplateClass): string {
return (template as TemplateBase).toDockerfile()
}
/**
* Build and deploy a template to E2B infrastructure.
*
* @param template The template to build
* @param name Template name in 'name' or 'name:tag' format
* @param options Optional build configuration options
*
* @example
* ```ts
* 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'] })
* ```
*/
static async build(
template: TemplateClass,
name: string,
options?: Omit<BuildOptions, 'alias'>
): Promise<BuildInfo>
/**
* Build and deploy a template to E2B infrastructure.
*
* @param template The template to build
* @param options Build configuration options with alias (deprecated)
*
* @deprecated Use the overload with `name` parameter instead.
* @example
* ```ts
* // Deprecated:
* await Template.build(template, { alias: 'my-python-env' })
*
* // Use instead:
* await Template.build(template, 'my-python-env:v1.0')
* ```
*/
static async build(
template: TemplateClass,
options: BuildOptions
): Promise<BuildInfo>
static async build(
template: TemplateClass,
nameOrOptions: string | BuildOptions,
options?: Omit<BuildOptions, 'alias'>
): Promise<BuildInfo> {
const { name, buildOptions } = normalizeBuildArguments(
nameOrOptions,
options
)
const buildOpts = this.resolveOpts(buildOptions) ?? {}
try {
buildOpts.onBuildLogs?.(new LogEntryStart(new Date(), 'Build started'))
const baseTemplate = template as TemplateBase
const config = new ConnectionConfig(buildOpts)
const client = new ApiClient(config)
const data = await baseTemplate.build(client, config, name, buildOpts)
buildOpts.onBuildLogs?.(
new LogEntry(new Date(), 'info', 'Waiting for logs...')
)
await waitForBuildFinish(client, {
templateID: data.templateId,
buildID: data.buildId,
onBuildLogs: buildOpts.onBuildLogs,
logsRefreshFrequency: baseTemplate.logsRefreshFrequency,
stackTraces: baseTemplate.stackTraces,
signal: buildOpts.signal,
requestTimeoutMs: config.requestTimeoutMs,
})
return data
} finally {
buildOpts.onBuildLogs?.(new LogEntryEnd(new Date(), 'Build finished'))
}
}
/**
* Build and deploy a template to E2B infrastructure without waiting for completion.
*
* @param template The template to build
* @param name Template name in 'name' or 'name:tag' format
* @param options Optional build configuration options
*
* @example
* ```ts
* 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'] })
* ```
*/
static async buildInBackground(
template: TemplateClass,
name: string,
options?: Omit<BuildOptions, 'alias'>
): Promise<BuildInfo>
/**
* Build and deploy a template to E2B infrastructure without waiting for completion.
*
* @param template The template to build
* @param options Build configuration options with alias (deprecated)
*
* @deprecated Use the overload with `name` parameter instead.
* @example
* ```ts
* // Deprecated:
* await Template.buildInBackground(template, { alias: 'my-python-env' })
*
* // Use instead:
* await Template.buildInBackground(template, 'my-python-env:v1.0')
* ```
*/
static async buildInBackground(
template: TemplateClass,
options: BuildOptions
): Promise<BuildInfo>
static async buildInBackground(
template: TemplateClass,
nameOrOptions: string | BuildOptions,
options?: Omit<BuildOptions, 'alias'>
): Promise<BuildInfo> {
const { name, buildOptions } = normalizeBuildArguments(
nameOrOptions,
options
)
const buildOpts = this.resolveOpts(buildOptions) ?? {}
const config = new ConnectionConfig(buildOpts)
const client = new ApiClient(config)
return (template as TemplateBase).build(client, config, name, buildOpts)
}
/**
* Get the status of a build.
*
* @param data Build identifiers
* @param options Authentication options
*
* @example
* ```ts
* const status = await Template.getBuildStatus(data)
* ```
*/
static async getBuildStatus(
data: Pick<BuildInfo, 'templateId' | 'buildId'>,
options?: GetBuildStatusOptions
): Promise<TemplateBuildStatusResponse> {
const config = new ConnectionConfig(this.resolveOpts(options))
const client = new ApiClient(config)
return await getBuildStatus(
client,
{
templateID: data.templateId,
buildID: data.buildId,
logsOffset: options?.logsOffset,
},
config.getSignal(undefined, options?.signal)
)
}
/**
* Check if a template with the given name exists.
*
* @param name Template name to check
* @param options Authentication options
* @returns True if the name exists, false otherwise
*
* @example
* ```ts
* const exists = await Template.exists('my-python-env')
* if (exists) {
* console.log('Template exists!')
* }
* ```
*/
static async exists(
name: string,
options?: ConnectionOpts
): Promise<boolean> {
return this.aliasExists(name, options)
}
/**
* Check if a template with the given alias exists.
*
* @param alias Template alias to check
* @param options Authentication options
* @returns True if the alias exists, false otherwise
*
* @deprecated Use `exists` instead.
* @example
* ```ts
* const exists = await Template.aliasExists('my-python-env')
* if (exists) {
* console.log('Template exists!')
* }
* ```
*/
static async aliasExists(
alias: string,
options?: ConnectionOpts
): Promise<boolean> {
const config = new ConnectionConfig(this.resolveOpts(options))
const client = new ApiClient(config)
return checkAliasExists(
client,
{ alias },
config.getSignal(undefined, options?.signal)
)
}
/**
* Assign tag(s) to an existing template build.
*
* @param targetName Template name in 'name:tag' format (the source build to tag from)
* @param tags Tag or tags to assign
* @param options Authentication options
* @returns Tag info with buildId and assigned tags
*
* @example
* ```ts
* // Assign a single tag
* await Template.assignTags('my-template:v1.0', 'production')
*
* // Assign multiple tags
* await Template.assignTags('my-template:v1.0', ['production', 'stable'])
* ```
*/
static async assignTags(
targetName: string,
tags: string | string[],
options?: ConnectionOpts
): Promise<TemplateTagInfo> {
const config = new ConnectionConfig(this.resolveOpts(options))
const client = new ApiClient(config)
const normalizedTags = Array.isArray(tags) ? tags : [tags]
return assignTags(
client,
{ targetName, tags: normalizedTags },
config.getSignal(undefined, options?.signal)
)
}
/**
* Remove tag(s) from a template.
*
* @param name Template name
* @param tags Tag or tags to remove
* @param options Authentication options
*
* @example
* ```ts
* // Remove a single tag
* await Template.removeTags('my-template', 'production')
*
* // Remove multiple tags from a template
* await Template.removeTags('my-template', ['production', 'staging'])
* ```
*/
static async removeTags(
name: string,
tags: string | string[],
options?: ConnectionOpts
): Promise<void> {
const config = new ConnectionConfig(this.resolveOpts(options))
const client = new ApiClient(config)
const normalizedTags = Array.isArray(tags) ? tags : [tags]
return removeTags(
client,
{ name, tags: normalizedTags },
config.getSignal(undefined, options?.signal)
)
}
/**
* Get all tags for a template.
*
* @param templateId Template ID or name
* @param options Authentication options
* @returns Array of tag details including tag name, buildId, and creation date
*
* @example
* ```ts
* const tags = await Template.getTags('my-template')
* for (const tag of tags) {
* console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`)
* }
* ```
*/
static async getTags(
templateId: string,
options?: ConnectionOpts
): Promise<TemplateTag[]> {
const config = new ConnectionConfig(this.resolveOpts(options))
const client = new ApiClient(config)
return getTemplateTags(
client,
{ templateID: templateId },
config.getSignal(undefined, options?.signal)
)
}
fromDebianImage(variant: string = 'stable'): TemplateBuilder {
return this.fromImage(`debian:${variant}`)
}
fromUbuntuImage(variant: string = 'latest'): TemplateBuilder {
return this.fromImage(`ubuntu:${variant}`)
}
fromFedoraImage(variant: string = '44'): TemplateBuilder {
return this.fromImage(`fedora:${variant}`)
}
fromAlpineImage(variant: string = '3.24'): TemplateBuilder {
return this.fromImage(`alpine:${variant}`)
}
// Left on `latest`: Arch is a rolling release and template provisioning runs
// `pacman -Syu`, so pinning a tag would not change the built result.
fromArchImage(variant: string = 'latest'): TemplateBuilder {
return this.fromImage(`archlinux:${variant}`)
}
fromPythonImage(version: string = '3'): TemplateBuilder {
return this.fromImage(`python:${version}`)
}
fromNodeImage(variant: string = 'lts'): TemplateBuilder {
return this.fromImage(`node:${variant}`)
}
fromBunImage(variant: string = 'latest'): TemplateBuilder {
return this.fromImage(`oven/bun:${variant}`)
}
fromBaseImage(): TemplateBuilder {
return this.fromImage(this.defaultBaseImage)
}
fromImage(
baseImage: string,
credentials?: { username: string; password: string }
): TemplateBuilder {
// Validate before mutating the builder.
if (credentials && (!credentials.username || !credentials.password)) {
throw new InvalidArgumentError(
'Both username and password are required when providing registry credentials',
getCallerFrame()
)
}
this.baseImage = baseImage
this.baseTemplate = undefined
// Set the registry config if provided
if (credentials) {
this.registryConfig = {
type: 'registry',
username: credentials.username,
password: credentials.password,
}
}
// If we should force the next layer and it's a FROM command, invalidate whole template
if (this.forceNextLayer) {
this.force = true
}
this.collectStackTrace()
return this
}
fromTemplate(template: string): TemplateBuilder {
this.baseTemplate = template
this.baseImage = undefined
// If we should force the next layer and it's a FROM command, invalidate whole template
if (this.forceNextLayer) {
this.force = true
}
this.collectStackTrace()
return this
}
fromDockerfile(dockerfileContentOrPath: string): TemplateBuilder {
// Each instruction parsed from the Dockerfile collects its own stack
// trace, which resolves to this method's call site
const { baseImage } = parseDockerfile(dockerfileContentOrPath, this)
this.baseImage = baseImage
this.baseTemplate = undefined
// If we should force the next layer and it's a FROM command, invalidate whole template
if (this.forceNextLayer) {
this.force = true
}
this.collectStackTrace()
return this
}
fromAWSRegistry(
image: string,
credentials: {
accessKeyId: string
secretAccessKey: string
region: string
}
): TemplateBuilder {
this.baseImage = image
this.baseTemplate = undefined
// Set the registry config if provided
this.registryConfig = {
type: 'aws',
awsAccessKeyId: credentials.accessKeyId,
awsSecretAccessKey: credentials.secretAccessKey,
awsRegion: credentials.region,
}
// If we should force the next layer and it's a FROM command, invalidate whole template
if (this.forceNextLayer) {
this.force = true
}
this.collectStackTrace()
return this
}
fromGCPRegistry(
image: string,
credentials: {
serviceAccountJSON: string | object
}
): TemplateBuilder {
this.baseImage = image
this.baseTemplate = undefined
// Set the registry config if provided
this.registryConfig = {
type: 'gcp',
serviceAccountJson: readGCPServiceAccountJSON(
this.fileContextPath.toString(),
credentials.serviceAccountJSON
),
}
// If we should force the next layer and it's a FROM command, invalidate whole template
if (this.forceNextLayer) {
this.force = true
}
this.collectStackTrace()
return this
}
copy(
src: PathLike | PathLike[],
dest: PathLike,
options?: {
forceUpload?: true
user?: string
mode?: number
resolveSymlinks?: boolean
gzip?: boolean
}
): TemplateBuilder {
if (runtime === 'browser') {
throw new Error('Browser runtime is not supported for copy')
}
const srcs = Array.isArray(src) ? src : [src]
const stackTrace = getCallerFrame()
for (const src of srcs) {
const srcString = src.toString()
// Validate that the source path is a relative path within the context directory
validateRelativePath(srcString, stackTrace)
const args = [
srcString,
dest.toString(),
options?.user ?? '',
options?.mode !== undefined ? padOctal(options.mode) : '',
]
this.instructions.push({
type: InstructionType.COPY,
args,
force: options?.forceUpload || this.forceNextLayer,
forceUpload: options?.forceUpload,
resolveSymlinks: options?.resolveSymlinks,
gzip: options?.gzip,
})
// Collect one stack trace per pushed instruction so build steps stay
// aligned with their stack traces when copying multiple sources
this.collectStackTrace()
}
return this
}
copyItems(items: CopyItem[]): TemplateBuilder {
if (runtime === 'browser') {
throw new Error('Browser runtime is not supported for copyItems')
}
// Stack trace that will be used to re-throw the error with
const stackTrace = getCallerFrame()
for (const item of items) {
try {
this.copy(item.src, item.dest, {
forceUpload: item.forceUpload,
user: item.user,
mode: item.mode,
resolveSymlinks: item.resolveSymlinks,
gzip: item.gzip,
})
} catch (error) {
const copyError = error as Error
copyError.stack = stackTrace
throw copyError
}
}
return this
}
remove(
path: PathLike | PathLike[],
options?: { force?: boolean; recursive?: boolean; user?: string }
): TemplateBuilder {
const paths = Array.isArray(path) ? path : [path]
const args = ['rm']
if (options?.recursive) {
args.push('-r')
}
if (options?.force) {
args.push('-f')
}
args.push(...paths.map((p) => shellQuote(p.toString())))
return this.runCmd(args.join(' '), { user: options?.user })
}
rename(
src: PathLike,
dest: PathLike,
options?: { force?: boolean; user?: string }
): TemplateBuilder {
const args = ['mv', shellQuote(src.toString()), shellQuote(dest.toString())]
if (options?.force) {
args.push('-f')
}
return this.runCmd(args.join(' '), { user: options?.user })
}
makeDir(
path: PathLike | PathLike[],
options?: { mode?: number; user?: string }
): TemplateBuilder {
const paths = Array.isArray(path) ? path : [path]
const args = ['mkdir', '-p']
if (options?.mode !== undefined) {
args.push(`-m ${padOctal(options.mode)}`)
}
args.push(...paths.map((p) => shellQuote(p.toString())))
return this.runCmd(args.join(' '), { user: options?.user })
}
makeSymlink(
src: PathLike,
dest: PathLike,
options?: { user?: string; force?: boolean }
): TemplateBuilder {
const args = ['ln', '-s']
if (options?.force) {
args.push('-f')
}
args.push(shellQuote(src.toString()), shellQuote(dest.toString()))
return this.runCmd(args.join(' '), { user: options?.user })
}
runCmd(command: string, options?: { user?: string }): TemplateBuilder
runCmd(commands: string[], options?: { user?: string }): TemplateBuilder
runCmd(
commandOrCommands: string | string[],
options?: { user?: string }
): TemplateBuilder {
const cmds = Array.isArray(commandOrCommands)
? commandOrCommands
: [commandOrCommands]
const args = [cmds.join(' && ')]
if (options?.user) {
args.push(options.user)
}
this.instructions.push({
type: InstructionType.RUN,
args,
force: this.forceNextLayer,
})
this.collectStackTrace()
return this
}
setWorkdir(workdir: PathLike): TemplateBuilder {
this.instructions.push({
type: InstructionType.WORKDIR,
args: [workdir.toString()],
force: this.forceNextLayer,
})
this.collectStackTrace()
return this
}
setUser(user: string): TemplateBuilder {
this.instructions.push({
type: InstructionType.USER,
args: [user],
force: this.forceNextLayer,
})
this.collectStackTrace()
return this
}
pipInstall(
packages?: string | string[],
options?: { g?: boolean }
): TemplateBuilder {
const g = options?.g ?? true
const args = ['pip', 'install']
const packageList = packages
? Array.isArray(packages)
? packages
: [packages]
: undefined
if (g === false) {
args.push('--user')
}
if (packageList) {
args.push(...packageList)
} else {
args.push('.')
}
return this.runCmd(args.join(' '), {
user: g ? 'root' : undefined,
})
}
npmInstall(
packages?: string | string[],
options?: { g?: boolean; dev?: boolean }
): TemplateBuilder {
const args = ['npm', 'install']
const packageList = packages
? Array.isArray(packages)
? packages
: [packages]
: undefined
if (options?.g) {
args.push('-g')
}
if (options?.dev) {
args.push('--save-dev')
}
if (packageList) {
args.push(...packageList)
}
return this.runCmd(args.join(' '), {
user: options?.g ? 'root' : undefined,
})
}
bunInstall(
packages?: string | string[],
options?: { g?: boolean; dev?: boolean }
): TemplateBuilder {
const args = ['bun', 'install']
const packageList = packages
? Array.isArray(packages)
? packages
: [packages]
: undefined
if (options?.g) {
args.push('-g')
}
if (options?.dev) {
args.push('--dev')
}
if (packageList) {
args.push(...packageList)
}
return this.runCmd(args.join(' '), {
user: options?.g ? 'root' : undefined,
})
}
aptInstall(
packages: string | string[],
options?: { noInstallRecommends?: boolean; fixMissing?: boolean }
): TemplateBuilder {
const packageList = Array.isArray(packages) ? packages : [packages]
return this.runCmd(
[
'apt-get update',
`DEBIAN_FRONTEND=noninteractive DEBCONF_NOWARNINGS=yes apt-get install -y ${options?.noInstallRecommends ? '--no-install-recommends ' : ''}${options?.fixMissing ? '--fix-missing ' : ''}${packageList.join(
' '
)}`,
],
{ user: 'root' }
)
}
addMcpServer(servers: McpServerName | McpServerName[]): TemplateBuilder {
if (this.baseTemplate !== 'mcp-gateway') {
throw new BuildError(
'MCP servers can only be added to mcp-gateway template',
getCallerFrame()
)
}
const serverList = Array.isArray(servers) ? servers : [servers]
return this.runCmd(`mcp-gateway pull ${serverList.join(' ')}`, {
user: 'root',
})
}
gitClone(
url: string,
path?: PathLike,
options?: { branch?: string; depth?: number; user?: string }
): TemplateBuilder {
const args = ['git', 'clone', shellQuote(url)]
if (options?.branch) {
args.push(`--branch ${shellQuote(options.branch)}`)
args.push('--single-branch')
}
if (options?.depth) {
args.push(`--depth ${options.depth}`)
}
if (path) {
args.push(shellQuote(path.toString()))
}
return this.runCmd(args.join(' '), { user: options?.user })
}
setStartCmd(
startCommand: string,
readyCommand: string | ReadyCmd
): TemplateFinal {
this.startCmd = startCommand
if (readyCommand instanceof ReadyCmd) {
this.readyCmd = readyCommand.getCmd()
} else {
this.readyCmd = readyCommand
}
this.collectStackTrace()
return this
}
setReadyCmd(readyCommand: string | ReadyCmd): TemplateFinal {
if (readyCommand instanceof ReadyCmd) {
this.readyCmd = readyCommand.getCmd()
} else {
this.readyCmd = readyCommand
}
this.collectStackTrace()
return this
}
setEnvs(envs: Record<string, string>): TemplateBuilder {
if (Object.keys(envs).length === 0) {
return this
}
this.instructions.push({
type: InstructionType.ENV,
args: Object.entries(envs).flatMap(([key, value]) => [key, value]),
force: this.forceNextLayer,
})
this.collectStackTrace()
return this
}
skipCache(): this {
this.forceNextLayer = true
return this
}
betaDevContainerPrebuild(devcontainerDirectory: string): TemplateBuilder {
if (this.baseTemplate !== 'devcontainer') {
throw new BuildError(
'Devcontainers can only used in the devcontainer template',
getCallerFrame()
)
}
return this.runCmd(
`devcontainer build --workspace-folder ${shellQuote(devcontainerDirectory)}`,
{ user: 'root' }
)
}
betaSetDevContainerStart(devcontainerDirectory: string): TemplateFinal {
if (this.baseTemplate !== 'devcontainer') {
throw new BuildError(
'Devcontainers can only used in the devcontainer template',
getCallerFrame()
)
}
const dir = shellQuote(devcontainerDirectory)
return this.setStartCmd(
`sudo devcontainer up --workspace-folder ${dir} && sudo /prepare-exec.sh ${dir} | sudo tee /devcontainer.sh > /dev/null && sudo chmod +x /devcontainer.sh && sudo touch /devcontainer.up`,
waitForFile('/devcontainer.up')
)
}
/**
* Collect the current stack trace for debugging purposes.
*
* The trace resolves to the first frame outside the SDK, so methods that
* delegate to other builder methods (e.g. `remove()` → `runCmd()`) collect
* the user's call site without any bookkeeping.
*
* @returns this for method chaining
*/
private collectStackTrace() {
this.stackTraces.push(getCallerFrame())
return this
}
/**
* Convert the template to JSON representation.
*
* @param computeHashes Whether to compute file hashes for COPY instructions
* @returns JSON string representation of the template
*/
private async toJSON(computeHashes: boolean): Promise<string> {
let instructions = this.instructions
if (computeHashes) {
instructions = await this.instructionsWithHashes()
}
return JSON.stringify(this.serialize(instructions), undefined, 2)
}
/**
* Convert the template to Dockerfile format.
*
* Note: Only templates based on Docker images can be converted to Dockerfile.
* Templates based on other E2B templates cannot be converted because they
* may use features not available in standard Dockerfiles.
*
* @returns Dockerfile string representation
* @throws Error if template is based on another E2B template or has no base image
*/
private toDockerfile(): string {
if (this.baseTemplate !== undefined) {
throw new Error(
'Cannot convert template built from another template to Dockerfile. ' +
'Templates based on other templates can only be built using the E2B API.'
)
}
if (this.baseImage === undefined) {
throw new Error('No base image specified for template')
}
let dockerfile = `FROM ${this.baseImage}\n`
for (const instruction of this.instructions) {
if (instruction.type === InstructionType.RUN) {
dockerfile += `RUN ${instruction.args[0]}\n`
continue
}
if (instruction.type === InstructionType.COPY) {
dockerfile += `COPY ${instruction.args[0]} ${instruction.args[1]}\n`
continue
}
if (instruction.type === InstructionType.ENV) {
const values: string[] = []
for (let i = 0; i < instruction.args.length; i += 2) {
values.push(`${instruction.args[i]}=${instruction.args[i + 1]}`)
}
dockerfile += `ENV ${values.join(' ')}\n`
continue
}
dockerfile += `${instruction.type} ${instruction.args.join(' ')}\n`
}
if (this.startCmd) {
dockerfile += `ENTRYPOINT ${this.startCmd}\n`
}
return dockerfile
}
/**
* Internal implementation of the template build process.
*
* @param client API client for communicating with E2B backend
* @param name Template name in 'name' or 'name:tag' format
* @param tags Additional tags to assign to the build
* @param options Build configuration options
* @throws BuildError if the build fails
*/
private async build(
client: ApiClient,
config: ConnectionConfig,
name: string,
options: Omit<BuildOptions, 'alias'>
): Promise<BuildInfo> {
if (options.skipCache) {
this.force = true
}
// Create template
options.onBuildLogs?.(
new LogEntry(
new Date(),
'info',
`Requesting build for template: ${name}${options.tags && options.tags.length > 0 ? ` with tags ${options.tags.join(', ')}` : ''}`
)
)
const {
templateID,
buildID,
tags: responseTags,
} = await requestBuild(
client,
{
name,
tags: options.tags,
cpuCount: options.cpuCount,
memoryMB: options.memoryMB,
minFreeDiskMb: options.minFreeDiskMb,
},
config.getSignal(undefined, options.signal)
)
options.onBuildLogs?.(
new LogEntry(
new Date(),
'info',
`Template created with ID: ${templateID}, Build ID: ${buildID}`
)
)
const instructionsWithHashes = await this.instructionsWithHashes()
// Upload files in parallel
const uploadPromises = instructionsWithHashes.map(
async (instruction, index) => {
if (instruction.type !== InstructionType.COPY) {
return
}
const src = instruction.args.length > 0 ? instruction.args[0] : null
const filesHash = instruction.filesHash ?? null
if (src === null || filesHash === null) {
throw new Error('Source path and files hash are required')
}
const forceUpload = instruction.forceUpload
let stackTrace = undefined
if (index + 1 >= 0 && index + 1 < this.stackTraces.length) {
stackTrace = this.stackTraces[index + 1]
}
const { present, url, headers } = await getFileUploadLink(
client,
{
templateID,
filesHash,
},
stackTrace,
config.getSignal(undefined, options.signal)
)
if (
(forceUpload && url != null) ||
(present === false && url != null)
) {
await uploadFile(
{
fileName: src,
fileContextPath: this.fileContextPath.toString(),
url,
headers,
ignorePatterns: [
...readDockerignore(this.fileContextPath.toString()),
...this.fileIgnorePatterns,
],
resolveSymlinks: instruction.resolveSymlinks ?? RESOLVE_SYMLINKS,
gzip: instruction.gzip ?? GZIP,
},
stackTrace,
// Forward `requestTimeoutMs` only when the caller set it — we
// never want to slap the 60s default on a multi-hundred-MB S3
// upload, but a user-set per-build timeout should govern the
// whole operation, including uploads.
{
signal: options.signal,
requestTimeoutMs: options.requestTimeoutMs,
}
)
options.onBuildLogs?.(
new LogEntry(new Date(), 'info', `Uploaded '${src}'`)
)
} else {
options.onBuildLogs?.(
new LogEntry(
new Date(),
'info',
`Skipping upload of '${src}', already cached`
)
)
}
}
)
await Promise.all(uploadPromises)
options.onBuildLogs?.(
new LogEntry(new Date(), 'info', 'All file uploads completed')
)
// Start build
options.onBuildLogs?.(
new LogEntry(new Date(), 'info', 'Starting building...')
)
await triggerBuild(
client,
{
templateID,
buildID,
template: this.serialize(instructionsWithHashes),
},
config.getSignal(undefined, options.signal)
)
return {
alias: name,
name: name,
tags: responseTags,
templateId: templateID,
buildId: buildID,
}
}
/**
* Add file hashes to COPY instructions for cache invalidation.
*
* @returns Copy of instructions array with filesHash added to COPY instructions
*/
private async instructionsWithHashes(): Promise<Instruction[]> {
return Promise.all(
this.instructions.map(async (instruction, index) => {
if (instruction.type !== InstructionType.COPY) {
return instruction
}
const src = instruction.args.length > 0 ? instruction.args[0] : null
const dest = instruction.args.length > 1 ? instruction.args[1] : null
if (src === null || dest === null) {
throw new Error('Source path and destination path are required')
}
let stackTrace = undefined
if (index + 1 >= 0 && index + 1 < this.stackTraces.length) {
stackTrace = this.stackTraces[index + 1]
}
return {
...instruction,
filesHash: await calculateFilesHash(
src,
dest,
this.fileContextPath.toString(),
[
...(runtime === 'browser'
? []
: readDockerignore(this.fileContextPath.toString())),
...this.fileIgnorePatterns,
],
instruction.resolveSymlinks ?? RESOLVE_SYMLINKS,
stackTrace
),
}
})
)
}
/**
* Serialize the template to the API request format.
*
* @param steps Array of build instructions with file hashes
* @returns Template data formatted for the API
*/
private serialize(steps: Instruction[]): TriggerBuildTemplate {
const templateData: TriggerBuildTemplate = {
startCmd: this.startCmd,
readyCmd: this.readyCmd,
steps,
force: this.force,
}
if (this.baseImage !== undefined) {
templateData.fromImage = this.baseImage
}
if (this.baseTemplate !== undefined) {
templateData.fromTemplate = this.baseTemplate
}
if (this.registryConfig !== undefined) {
templateData.fromImageRegistry = this.registryConfig
}
return templateData
}
}
/**
* Builder and API entrypoint for E2B sandbox templates.
*
* `Template` is the {@link TemplateBase} class, wrapped so it can also be
* called as a factory returning a builder. The statics (`Template.build`,
* `Template.exists`, …) resolve their connection options off the class they are
* called on — so a subclass can bind its own defaults.
*
* @param options Optional builder options, e.g. the file context path used to
* resolve relative paths passed to `copy`
* @returns A template builder
*
* @example
* ```ts
* import { Template } from 'e2b'
*
* const template = Template()
* .fromPythonImage('3')
* .copy('requirements.txt', '/app/')
* .pipInstall()
*
* await Template.build(template, 'my-python-app:v1.0')
* ```
*/
export const Template = callableTemplate(TemplateBase)
export type {
BuildInfo,
BuildOptions,
BuildStatusReason,
CopyItem,
GetBuildStatusOptions,
McpServerName,
TemplateBuilder,
TemplateBuildStatus,
TemplateBuildStatusResponse,
TemplateClass,
TemplateTag,
TemplateTagInfo,
} from './types'