> ## Documentation Index
> Fetch the complete documentation index at: https://e2b-docs-prime-agent-page.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Template

## TemplateBuildStatus

```python theme={null}
class TemplateBuildStatus(str, Enum)
```

Status of a template build.

## BuildStatusReason

```python theme={null}
@dataclass
class BuildStatusReason()
```

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

### message

Message with the status reason.

### step

Step that failed.

### log\_entries

Log entries related to the status reason.

## TemplateBuildStatusResponse

```python theme={null}
@dataclass
class TemplateBuildStatusResponse()
```

Response from getting build status.

### build\_id

Build identifier.

### template\_id

Template identifier.

### status

Current status of the build.

### log\_entries

Build log entries.

### logs

Build logs (raw strings). Deprecated: use log\_entries instead.

### reason

Reason for the current status (typically for errors).

## TemplateTagInfo

```python theme={null}
@dataclass
class TemplateTagInfo()
```

Information about assigned template tags.

### build\_id

Build identifier associated with this tag.

### tags

Assigned tags of the template.

## TemplateTag

```python theme={null}
@dataclass
class TemplateTag()
```

Detailed information about a single template tag.

### tag

Name of the tag.

### build\_id

Build identifier associated with this tag.

### created\_at

When this tag was assigned.

## InstructionType

```python theme={null}
class InstructionType(str, Enum)
```

Types of instructions that can be used in a template.

## CopyItem

```python theme={null}
class CopyItem(TypedDict)
```

Configuration for a single file/directory copy operation.

## Instruction

```python theme={null}
class Instruction(TypedDict)
```

Represents a single instruction in the template build process.

## GenericDockerRegistry

```python theme={null}
class GenericDockerRegistry(TypedDict)
```

Configuration for a generic Docker registry with basic authentication.

## AWSRegistry

```python theme={null}
class AWSRegistry(TypedDict)
```

Configuration for AWS Elastic Container Registry (ECR).

## GCPRegistry

```python theme={null}
class GCPRegistry(TypedDict)
```

Configuration for Google Container Registry (GCR) or Artifact Registry.

## TemplateType

```python theme={null}
class TemplateType(TypedDict)
```

Internal representation of a template for the E2B build API.

## BuildInfo

```python theme={null}
@dataclass
class BuildInfo()
```

Information about a built template.

## TemplateBuilder

```python theme={null}
class TemplateBuilder()
```

Builder class for adding instructions to an E2B template.

All methods return self to allow method chaining.

### copy

```python theme={null}
def copy(src: Union[Union[str, Path], List[Union[str, Path]]],
         dest: Union[str, Path],
         force_upload: Optional[Literal[True]] = None,
         user: Optional[str] = None,
         mode: Optional[int] = None,
         resolve_symlinks: Optional[bool] = None,
         gzip: Optional[bool] = None) -> "TemplateBuilder"
```

Copy files or directories from the local filesystem into the template.

**Arguments**:

* `src`: Source file(s) or directory path(s) to copy
* `dest`: Destination path in the template
* `force_upload`: Force upload even if files are cached
* `user`: User and optionally group (user:group) to own the files
* `mode`: File permissions in octal format (e.g., 0o755)
* `resolve_symlinks`: Whether to resolve symlinks
* `gzip`: Whether to gzip the files before upload (default: True)

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.copy('requirements.txt', '/home/user/')
template.copy(['app.py', 'config.py'], '/app/', mode=0o755)
```

### copy\_items

```python theme={null}
def copy_items(items: List[CopyItem]) -> "TemplateBuilder"
```

Copy multiple files or directories using a list of copy items.

**Arguments**:

* `items`: List of CopyItem dictionaries with src, dest, and optional parameters

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.copy_items([
    {'src': 'app.py', 'dest': '/app/'},
    {'src': 'config.py', 'dest': '/app/', 'mode': 0o644}
])
```

### remove

```python theme={null}
def remove(path: Union[Union[str, Path], List[Union[str, Path]]],
           force: bool = False,
           recursive: bool = False,
           user: Optional[str] = None) -> "TemplateBuilder"
```

Remove files or directories in the template.

**Arguments**:

* `path`: File(s) or directory path(s) to remove
* `force`: Force removal without prompting
* `recursive`: Remove directories recursively
* `user`: User to run the command as

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.remove('/tmp/cache', recursive=True, force=True)
template.remove('/tmp/cache', recursive=True, force=True, user='root')
```

### rename

```python theme={null}
def rename(src: Union[str, Path],
           dest: Union[str, Path],
           force: bool = False,
           user: Optional[str] = None) -> "TemplateBuilder"
```

Rename or move a file or directory in the template.

**Arguments**:

* `src`: Source path
* `dest`: Destination path
* `force`: Force rename without prompting
* `user`: User to run the command as

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.rename('/tmp/old.txt', '/tmp/new.txt')
template.rename('/tmp/old.txt', '/tmp/new.txt', user='root')
```

### make\_dir

```python theme={null}
def make_dir(path: Union[Union[str, Path], List[Union[str, Path]]],
             mode: Optional[int] = None,
             user: Optional[str] = None) -> "TemplateBuilder"
```

Create directory(ies) in the template.

**Arguments**:

* `path`: Directory path(s) to create
* `mode`: Directory permissions in octal format (e.g., 0o755)
* `user`: User to run the command as

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.make_dir('/app/data', mode=0o755)
template.make_dir(['/app/logs', '/app/cache'])
template.make_dir('/app/data', mode=0o755, user='root')
```

### make\_symlink

```python theme={null}
def make_symlink(src: Union[str, Path],
                 dest: Union[str, Path],
                 user: Optional[str] = None,
                 force: bool = False) -> "TemplateBuilder"
```

Create a symbolic link in the template.

**Arguments**:

* `src`: Source path (target of the symlink)
* `dest`: Destination path (location of the symlink)
* `user`: User to run the command as
* `force`: Force symlink without prompting

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.make_symlink('/usr/bin/python3', '/usr/bin/python')
template.make_symlink('/usr/bin/python3', '/usr/bin/python', user='root')
template.make_symlink('/usr/bin/python3', '/usr/bin/python', force=True)
```

### run\_cmd

```python theme={null}
def run_cmd(command: Union[str, List[str]],
            user: Optional[str] = None) -> "TemplateBuilder"
```

Run a shell command during template build.

**Arguments**:

* `command`: Command string or list of commands to run (joined with &&)
* `user`: User to run the command as

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.run_cmd('apt-get update')
template.run_cmd(['pip install numpy', 'pip install pandas'])
template.run_cmd('apt-get install vim', user='root')
```

### set\_workdir

```python theme={null}
def set_workdir(workdir: Union[str, Path]) -> "TemplateBuilder"
```

Set the working directory for subsequent commands in the template.

**Arguments**:

* `workdir`: Path to set as the working directory

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.set_workdir('/app')
```

### set\_user

```python theme={null}
def set_user(user: str) -> "TemplateBuilder"
```

Set the user for subsequent commands in the template.

**Arguments**:

* `user`: Username to set

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.set_user('root')
```

### pip\_install

```python theme={null}
def pip_install(packages: Optional[Union[str, List[str]]] = None,
                g: bool = True) -> "TemplateBuilder"
```

Install Python packages using pip.

**Arguments**:

* `packages`: Package name(s) to install. If None, runs 'pip install .' in the current directory
* `g`: Install packages globally (default: True). If False, installs for user only

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.pip_install('numpy')
template.pip_install(['pandas', 'scikit-learn'])
template.pip_install('numpy', g=False)  # Install for user only
template.pip_install()  # Installs from current directory
```

### npm\_install

```python theme={null}
def npm_install(packages: Optional[Union[str, List[str]]] = None,
                g: Optional[bool] = False,
                dev: Optional[bool] = False) -> "TemplateBuilder"
```

Install Node.js packages using npm.

**Arguments**:

* `packages`: Package name(s) to install. If None, installs from package.json
* `g`: Install packages globally
* `dev`: Install packages as dev dependencies

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.npm_install('express')
template.npm_install(['lodash', 'axios'])
template.npm_install('typescript', g=True)
template.npm_install()  # Installs from package.json
```

### bun\_install

```python theme={null}
def bun_install(packages: Optional[Union[str, List[str]]] = None,
                g: Optional[bool] = False,
                dev: Optional[bool] = False) -> "TemplateBuilder"
```

Install Bun packages using bun.

**Arguments**:

* `packages`: Package name(s) to install. If None, installs from package.json
* `g`: Install packages globally
* `dev`: Install packages as dev dependencies

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.bun_install('express')
template.bun_install(['lodash', 'axios'])
template.bun_install('tsx', g=True)
template.bun_install('typescript', dev=True)
template.bun_install()  # Installs from package.json
```

### apt\_install

```python theme={null}
def apt_install(packages: Union[str, List[str]],
                no_install_recommends: bool = False,
                fix_missing: bool = False) -> "TemplateBuilder"
```

Install system packages using apt-get.

**Arguments**:

* `packages`: Package name(s) to install
* `no_install_recommends`: Whether to skip installing recommended packages
* `fix_missing`: Whether to fix missing packages

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.apt_install('vim')
template.apt_install(['git', 'curl', 'wget'])
template.apt_install('vim', fix_missing=True)
```

### add\_mcp\_server

```python theme={null}
def add_mcp_server(servers: Union[str, List[str]]) -> "TemplateBuilder"
```

Install MCP servers using mcp-gateway.

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

**Arguments**:

* `servers`: MCP server name(s)

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.add_mcp_server('exa')
template.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
```

### git\_clone

```python theme={null}
def git_clone(url: str,
              path: Optional[Union[str, Path]] = None,
              branch: Optional[str] = None,
              depth: Optional[int] = None,
              user: Optional[str] = None) -> "TemplateBuilder"
```

Clone a git repository into the template.

**Arguments**:

* `url`: Git repository URL
* `path`: Destination path for the clone
* `branch`: Branch to clone
* `depth`: Clone depth for shallow clones
* `user`: User to run the command as

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.git_clone('https://github.com/user/repo.git', '/app/repo')
template.git_clone('https://github.com/user/repo.git', branch='main', depth=1)
template.git_clone('https://github.com/user/repo.git', '/app/repo', user='root')
```

### beta\_dev\_container\_prebuild

```python theme={null}
def beta_dev_container_prebuild(
        devcontainer_directory: Union[str, Path]) -> "TemplateBuilder"
```

Prebuild a devcontainer from the specified directory during the build process.

**Arguments**:

* `devcontainer_directory`: Path to the devcontainer directory

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.git_clone('https://myrepo.com/project.git', '/my-devcontainer')
template.beta_dev_container_prebuild('/my-devcontainer')
```

### beta\_set\_dev\_container\_start

```python theme={null}
def beta_set_dev_container_start(
        devcontainer_directory: Union[str, Path]) -> "TemplateFinal"
```

Start a devcontainer from the specified directory and set it as the start command.

This method returns `TemplateFinal`, which means it must be the last method in the chain.

**Arguments**:

* `devcontainer_directory`: Path to the devcontainer directory

**Returns**:

`TemplateFinal` class
Example

```python theme={null}
template.git_clone('https://myrepo.com/project.git', '/my-devcontainer')
template.beta_set_devcontainer_start('/my-devcontainer')

template.git_clone('https://myrepo.com/project.git', '/my-devcontainer')
template.beta_dev_container_prebuild('/my-devcontainer')
template.beta_set_dev_container_start('/my-devcontainer')
```

### set\_envs

```python theme={null}
def set_envs(envs: Dict[str, str]) -> "TemplateBuilder"
```

Set environment variables.

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

**Arguments**:

* `envs`: Dictionary of environment variable names and values

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.set_envs({'NODE_ENV': 'production', 'PORT': '8080'})
```

### skip\_cache

```python theme={null}
def skip_cache() -> "TemplateBuilder"
```

Skip cache for all subsequent build instructions from this point.

Call this before any instruction to force it and all following layers
to be rebuilt, ignoring any cached layers.

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
template.skip_cache().run_cmd('apt-get update')
```

### set\_start\_cmd

```python theme={null}
def set_start_cmd(start_cmd: str,
                  ready_cmd: Union[str, ReadyCmd]) -> "TemplateFinal"
```

Set the command to start when the sandbox launches and the ready check command.

**Arguments**:

* `start_cmd`: Command to run when the sandbox starts
* `ready_cmd`: Command or ReadyCmd to check if the sandbox is ready

**Returns**:

`TemplateFinal` class
Example

```python theme={null}
template.set_start_cmd(
    'python app.py',
    'curl http://localhost:8000/health'
)

from e2b import wait_for_port, wait_for_url

template.set_start_cmd(
    'python -m http.server 8000',
    wait_for_port(8000)
)

template.set_start_cmd(
    'npm start',
    wait_for_url('http://localhost:3000/health', 200)
)
```

### set\_ready\_cmd

```python theme={null}
def set_ready_cmd(ready_cmd: Union[str, ReadyCmd]) -> "TemplateFinal"
```

Set the command to check if the sandbox is ready.

**Arguments**:

* `ready_cmd`: Command or ReadyCmd to check if the sandbox is ready

**Returns**:

`TemplateFinal` class
Example

```python theme={null}
template.set_ready_cmd('curl http://localhost:8000/health')

from e2b import wait_for_port, wait_for_file, wait_for_process

template.set_ready_cmd(wait_for_port(3000))

template.set_ready_cmd(wait_for_file('/tmp/ready'))

template.set_ready_cmd(wait_for_process('nginx'))
```

## TemplateFinal

```python theme={null}
class TemplateFinal()
```

Final template state after start/ready commands are set.

## TemplateBase

```python theme={null}
class TemplateBase()
```

Base class for building E2B sandbox templates.

### \_\_init\_\_

```python theme={null}
def __init__(file_context_path: Optional[Union[str, Path]] = None,
             file_ignore_patterns: Optional[List[str]] = None)
```

Create a new template builder instance.

**Arguments**:

* `file_context_path`: Base path for resolving relative file paths in copy operations
* `file_ignore_patterns`: List of glob patterns to ignore when copying files

### skip\_cache

```python theme={null}
def skip_cache() -> "TemplateBase"
```

Skip cache for all subsequent build instructions from this point.

**Returns**:

`TemplateBase` class
Example

```python theme={null}
template.skip_cache().from_python_image('3.11')
```

### from\_debian\_image

```python theme={null}
def from_debian_image(variant: str = "stable") -> TemplateBuilder
```

Start template from a Debian base image.

**Arguments**:

* `variant`: Debian image variant

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_debian_image('bookworm')
```

### from\_ubuntu\_image

```python theme={null}
def from_ubuntu_image(variant: str = "latest") -> TemplateBuilder
```

Start template from an Ubuntu base image.

**Arguments**:

* `variant`: Ubuntu image variant (default: 'latest')

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_ubuntu_image('24.04')
```

### from\_python\_image

```python theme={null}
def from_python_image(version: str = "3") -> TemplateBuilder
```

Start template from a Python base image.

**Arguments**:

* `version`: Python version (default: '3')

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_python_image('3')
```

### from\_node\_image

```python theme={null}
def from_node_image(variant: str = "lts") -> TemplateBuilder
```

Start template from a Node.js base image.

**Arguments**:

* `variant`: Node.js image variant (default: 'lts')

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_node_image('24')
```

### from\_bun\_image

```python theme={null}
def from_bun_image(variant: str = "latest") -> TemplateBuilder
```

Start template from a Bun base image.

**Arguments**:

* `variant`: Bun image variant (default: 'latest')

**Returns**:

`TemplateBuilder` class

### from\_base\_image

```python theme={null}
def from_base_image() -> TemplateBuilder
```

Start template from the E2B base image (e2bdev/base:latest).

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_base_image()
```

### from\_image

```python theme={null}
def from_image(image: str,
               username: Optional[str] = None,
               password: Optional[str] = None) -> TemplateBuilder
```

Start template from a Docker image.

**Arguments**:

* `image`: Docker image name (e.g., 'ubuntu:24.04')
* `username`: Username for private registry authentication
* `password`: Password for private registry authentication

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_image('python:3')

Template().from_image('myregistry.com/myimage:latest', username='user', password='pass')
```

### from\_template

```python theme={null}
def from_template(template: str) -> TemplateBuilder
```

Start template from an existing E2B template.

**Arguments**:

* `template`: E2B template ID or alias

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_template('my-base-template')
```

### from\_dockerfile

```python theme={null}
def from_dockerfile(dockerfile_content_or_path: str) -> TemplateBuilder
```

Parse a Dockerfile and convert it to Template SDK format.

**Arguments**:

* `dockerfile_content_or_path`: Either the Dockerfile content as a string, or a path to a Dockerfile file

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_dockerfile('Dockerfile')
Template().from_dockerfile('FROM python:3\nRUN pip install numpy')
```

### from\_aws\_registry

```python theme={null}
def from_aws_registry(image: str, access_key_id: str, secret_access_key: str,
                      region: str) -> TemplateBuilder
```

Start template from an AWS ECR registry image.

**Arguments**:

* `image`: Docker image name from AWS ECR
* `access_key_id`: AWS access key ID
* `secret_access_key`: AWS secret access key
* `region`: AWS region

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_aws_registry(
    '123456789.dkr.ecr.us-west-2.amazonaws.com/myimage:latest',
    access_key_id='AKIA...',
    secret_access_key='...',
    region='us-west-2'
)
```

### from\_gcp\_registry

```python theme={null}
def from_gcp_registry(
        image: str, service_account_json: Union[str, dict]) -> TemplateBuilder
```

Start template from a GCP Artifact Registry or Container Registry image.

**Arguments**:

* `image`: Docker image name from GCP registry
* `service_account_json`: Service account JSON string, dict, or path to JSON file

**Returns**:

`TemplateBuilder` class
Example

```python theme={null}
Template().from_gcp_registry(
    'gcr.io/myproject/myimage:latest',
    service_account_json='path/to/service-account.json'
)
```

### to\_json

```python theme={null}
@staticmethod
def to_json(template: "TemplateClass") -> str
```

Convert a template to JSON representation.

**Arguments**:

* `template`: The template to convert (TemplateBuilder or TemplateFinal instance)

**Returns**:

JSON string representation of the template
Example

```python theme={null}
template = Template().from_python_image('3').copy('app.py', '/app/')
json_str = TemplateBase.to_json(template)
```

### to\_dockerfile

```python theme={null}
@staticmethod
def to_dockerfile(template: "TemplateClass") -> str
```

Convert a template to Dockerfile format.

Note: Templates based on other E2B templates cannot be converted to Dockerfile.

**Arguments**:

* `template`: The template to convert (TemplateBuilder or TemplateFinal instance)

**Raises**:

* `ValueError`: If the template is based on another E2B template or has no base image
  Example

```python theme={null}
template = Template().from_python_image('3').copy('app.py', '/app/')
dockerfile = TemplateBase.to_dockerfile(template)
```

**Returns**:

Dockerfile string representation

Special step name for the finalization phase of template building.
This is the last step that runs after all user-defined instructions.

### FINALIZE\_STEP\_NAME

Special step name for the base image phase of template building.
This is the first step that sets up the base image.

### BASE\_STEP\_NAME

Default setting for whether to resolve symbolic links when copying files.
When False, symlinks are copied as symlinks rather than following them.

### RESOLVE\_SYMLINKS

Default setting for whether to gzip files when copying them into the
template. When True, the upload archive is gzipped before being uploaded.

### GZIP

Default timeout (in seconds) for uploading the build-context archive to the
S3 presigned URL. Uploads of large archives can take far longer than the 60s
general API request timeout, so the upload uses a 1-hour default unless the
caller passes an explicit `request_timeout`. This matches the JS SDK's
`FILE_UPLOAD_TIMEOUT_MS`.

## ReadyCmd

```python theme={null}
class ReadyCmd()
```

Wrapper class for ready check commands.

### wait\_for\_port

```python theme={null}
def wait_for_port(port: int)
```

Wait for a port to be listening.

Uses `ss` command to check if a port is open and listening.

**Arguments**:

* `port`: Port number to wait for

**Returns**:

ReadyCmd that checks for the port
Example

```python theme={null}
from e2b import Template, wait_for_port

template = (
    Template()
    .from_python_image()
    .set_start_cmd('python -m http.server 8000', wait_for_port(8000))
)
```

### wait\_for\_url

```python theme={null}
def wait_for_url(url: str, status_code: int = 200)
```

Wait for a URL to return a specific HTTP status code.

Uses `curl` to make HTTP requests and check the response status.

**Arguments**:

* `url`: URL to check (e.g., '[http://localhost:3000/health](http://localhost:3000/health)')
* `status_code`: Expected HTTP status code (default: 200)

**Returns**:

ReadyCmd that checks the URL
Example

```python theme={null}
from e2b import Template, wait_for_url

template = (
    Template()
    .from_node_image()
    .set_start_cmd('npm start', wait_for_url('http://localhost:3000/health'))
)
```

### wait\_for\_process

```python theme={null}
def wait_for_process(process_name: str)
```

Wait for a process with a specific name to be running.

Uses `pgrep` to check if a process exists.

**Arguments**:

* `process_name`: Name of the process to wait for

**Returns**:

ReadyCmd that checks for the process
Example

```python theme={null}
from e2b import Template, wait_for_process

template = (
    Template()
    .from_base_image()
    .set_start_cmd('./my-daemon', wait_for_process('my-daemon'))
)
```

### wait\_for\_file

```python theme={null}
def wait_for_file(filename: str)
```

Wait for a file to exist.

Uses shell test command to check file existence.

**Arguments**:

* `filename`: Path to the file to wait for

**Returns**:

ReadyCmd that checks for the file
Example

```python theme={null}
from e2b import Template, wait_for_file

template = (
    Template()
    .from_base_image()
    .set_start_cmd('./init.sh', wait_for_file('/tmp/ready'))
)
```

### wait\_for\_timeout

```python theme={null}
def wait_for_timeout(timeout: int)
```

Wait for a specified timeout before considering the sandbox ready.

Uses `sleep` command to wait for a fixed duration.

**Arguments**:

* `timeout`: Time to wait in **milliseconds** (minimum: 1000ms / 1 second)

**Returns**:

ReadyCmd that waits for the specified duration
Example

```python theme={null}
from e2b import Template, wait_for_timeout

template = (
    Template()
    .from_node_image()
    .set_start_cmd('npm start', wait_for_timeout(5000))  # Wait 5 seconds
)
```

## DockerfFileFinalParserInterface

```python theme={null}
class DockerfFileFinalParserInterface(Protocol)
```

Protocol defining the final interface for Dockerfile parsing callbacks.

## DockerfileParserInterface

```python theme={null}
class DockerfileParserInterface(Protocol)
```

Protocol defining the interface for Dockerfile parsing callbacks.

### run\_cmd

```python theme={null}
def run_cmd(command: Union[str, List[str]],
            user: Optional[str] = None) -> "DockerfileParserInterface"
```

Handle RUN instruction.

### copy

```python theme={null}
def copy(src: str,
         dest: str,
         force_upload: Optional[Literal[True]] = None,
         user: Optional[str] = None,
         mode: Optional[int] = None,
         resolve_symlinks: Optional[bool] = None,
         gzip: Optional[bool] = None) -> "DockerfileParserInterface"
```

Handle COPY instruction.

### set\_workdir

```python theme={null}
def set_workdir(workdir: str) -> "DockerfileParserInterface"
```

Handle WORKDIR instruction.

### set\_user

```python theme={null}
def set_user(user: str) -> "DockerfileParserInterface"
```

Handle USER instruction.

### set\_envs

```python theme={null}
def set_envs(envs: Dict[str, str]) -> "DockerfileParserInterface"
```

Handle ENV instruction.

### set\_start\_cmd

```python theme={null}
def set_start_cmd(start_cmd: str,
                  ready_cmd: str) -> "DockerfFileFinalParserInterface"
```

Handle CMD/ENTRYPOINT instruction.

### parse\_dockerfile

```python theme={null}
def parse_dockerfile(dockerfile_content_or_path: str,
                     template_builder: DockerfileParserInterface) -> str
```

Parse a Dockerfile and convert it to Template SDK format.

**Arguments**:

* `dockerfile_content_or_path`: Either the Dockerfile content as a string, or a path to a Dockerfile file
* `template_builder`: Interface providing template builder methods

**Raises**:

* `ValueError`: If the Dockerfile is invalid or unsupported

**Returns**:

The base image from the Dockerfile

## LogEntry

```python theme={null}
@dataclass
class LogEntry()
```

Represents a single log entry from the template build process.

## LogEntryStart

```python theme={null}
@dataclass
class LogEntryStart(LogEntry)
```

Special log entry indicating the start of a build process.

## LogEntryEnd

```python theme={null}
@dataclass
class LogEntryEnd(LogEntry)
```

Special log entry indicating the end of a build process.

### TIMER\_UPDATE\_INTERVAL\_MS

Default minimum log level to display.

### DEFAULT\_LEVEL

Colored labels for each log level.

### levels

Numeric ordering of log levels for comparison (lower = less severe).

### set\_interval

```python theme={null}
def set_interval(func, interval)
```

Returns a stop function that can be called to cancel the interval.

Similar to JavaScript's setInterval.

**Arguments**:

* `func`: Function to execute at each interval
* `interval`: Interval duration in **seconds**

**Returns**:

Stop function that can be called to cancel the interval

### default\_build\_logger

```python theme={null}
def default_build_logger(
        min_level: Optional[LogEntryLevel] = None
) -> Callable[[LogEntry], None]
```

Create a default build logger with animated timer display.

**Arguments**:

* `min_level`: Minimum log level to display (default: 'info')

**Returns**:

Logger function that accepts LogEntry instances
Example

```python theme={null}
from e2b import Template, default_build_logger

template = Template().from_python_image()

```

### make\_traceback

```python theme={null}
def make_traceback(
        caller_frame: Optional[FrameType]) -> Optional[TracebackType]
```

Create a TracebackType from a caller frame for error reporting.

**Arguments**:

* `caller_frame`: The caller's frame object, or None

**Returns**:

A TracebackType object for use with exception.with\_traceback(), or None

### validate\_relative\_path

```python theme={null}
def validate_relative_path(src: str,
                           stack_trace: Optional[TracebackType]) -> None
```

Validate that a source path for copy operations is a relative path that stays

within the context directory. This prevents path traversal attacks and ensures
files are copied from within the expected directory.

**Arguments**:

* `src`: The source path to validate
* `stack_trace`: Optional stack trace for error reporting

**Raises**:

* `TemplateException`: If the path is absolute or escapes the context directory
  Invalid paths:
* Absolute paths: /absolute/path, C:\Windows\path
* Parent directory escapes: ../foo, foo/../../bar, ./foo/../../../bar

Valid paths:

* Simple relative: foo, foo/bar
* Current directory prefix: ./foo, ./foo/bar
* Internal parent refs that don't escape: foo/../bar (stays within context)

### normalize\_build\_arguments

```python theme={null}
def normalize_build_arguments(name: Optional[str] = None,
                              alias: Optional[str] = None) -> str
```

Normalize build arguments from different parameter signatures.

Handles string name or legacy alias parameter.

**Arguments**:

* `name`: Template name in 'name' or 'name:tag' format
* `alias`: (Deprecated) Alias name for the template. Use name instead.

**Raises**:

* `TemplateException`: If no template name is provided

**Returns**:

Normalized template name

### read\_dockerignore

```python theme={null}
def read_dockerignore(context_path: str) -> List[str]
```

Read and parse a .dockerignore file.

**Arguments**:

* `context_path`: Directory path containing the .dockerignore file

**Returns**:

Array of ignore patterns (empty lines and comments are filtered out)

### normalize\_path

```python theme={null}
def normalize_path(path: str) -> str
```

Normalize path separators to forward slashes for glob patterns (glob expects / even on Windows).

**Arguments**:

* `path`: The path to normalize

**Returns**:

The normalized path

### get\_all\_files\_in\_path

```python theme={null}
def get_all_files_in_path(src: str,
                          context_path: str,
                          ignore_patterns: List[str],
                          include_directories: bool = True) -> List[str]
```

Get all files for a given path and ignore patterns.

**Arguments**:

* `src`: Path to the source directory
* `context_path`: Base directory for resolving relative paths
* `ignore_patterns`: Ignore patterns
* `include_directories`: Whether to include directories

**Returns**:

Array of files

### calculate\_files\_hash

```python theme={null}
def calculate_files_hash(src: str, dest: str, context_path: str,
                         ignore_patterns: List[str], resolve_symlinks: bool,
                         stack_trace: Optional[TracebackType]) -> str
```

Calculate a hash of files being copied to detect changes for cache invalidation.

The hash includes file content, metadata (mode, size), and relative paths.
Note: uid, gid, and mtime are excluded to ensure stable hashes across environments.

**Arguments**:

* `src`: Source path pattern for files to copy
* `dest`: Destination path where files will be copied
* `context_path`: Base directory for resolving relative paths
* `ignore_patterns`: Glob patterns to ignore
* `resolve_symlinks`: Whether to resolve symbolic links when hashing
* `stack_trace`: Optional stack trace for error reporting

**Raises**:

* `ValueError`: If no files match the source pattern

**Returns**:

Hex string hash of all files

### tar\_file\_stream

```python theme={null}
def tar_file_stream(file_name: str, file_context_path: str,
                    ignore_patterns: List[str], resolve_symlinks: bool,
                    gzip: bool) -> IO[bytes]
```

Create a tar archive of files matching a pattern in a temporary file.

The archive is spooled to disk so it can be uploaded as a stream instead
of being buffered in memory. The temporary file is deleted when closed.

**Arguments**:

* `file_name`: Glob pattern for files to include
* `file_context_path`: Base directory for resolving file paths
* `ignore_patterns`: Ignore patterns
* `resolve_symlinks`: Whether to resolve symbolic links
* `gzip`: Whether to gzip the archive

**Returns**:

Binary file object positioned at the start of the archive

### strip\_ansi\_escape\_codes

```python theme={null}
def strip_ansi_escape_codes(text: str) -> str
```

Strip ANSI escape codes from a string.

Source: [https://github.com/chalk/ansi-regex/blob/main/index.js](https://github.com/chalk/ansi-regex/blob/main/index.js)

**Arguments**:

* `text`: String with ANSI escape codes

**Returns**:

String without ANSI escape codes

### get\_caller\_frame

```python theme={null}
def get_caller_frame() -> Optional[FrameType]
```

Get the caller's stack frame in user code.

This is used to provide better error messages and debugging information
by tracking where template methods were called from in user code.

The caller is the first frame whose file lies outside the SDK package.
Selecting frames by boundary rather than by fixed depth keeps the result
stable no matter how many SDK-internal frames sit in between.

**Returns**:

The caller frame, or None if not available

### get\_caller\_directory

```python theme={null}
def get_caller_directory() -> Optional[str]
```

Get the directory of the caller in user code.

This is used to determine the file\_context\_path when creating a template,
so file paths are resolved relative to the user's template file location.

**Returns**:

The caller's directory path, or None if not available

### pad\_octal

```python theme={null}
def pad_octal(mode: int) -> str
```

Convert a numeric file mode to a zero-padded octal string.

**Arguments**:

* `mode`: File mode as a number (e.g., 493 for 0o755)

**Returns**:

Zero-padded 4-digit octal string (e.g., "0755")
Example

```python theme={null}
pad_octal(0o755)  # Returns "0755"
pad_octal(0o644)  # Returns "0644"
```

### get\_build\_step\_index

```python theme={null}
def get_build_step_index(step: str, stack_traces_length: int) -> int
```

Get the array index for a build step based on its name.

Special steps:

* BASE\_STEP\_NAME: Returns 0 (first step)
* FINALIZE\_STEP\_NAME: Returns the last index
* Numeric strings: Converted to number

**Arguments**:

* `step`: Build step name or number as string
* `stack_traces_length`: Total number of stack traces (used for FINALIZE\_STEP\_NAME)

**Returns**:

Index for the build step

### read\_gcp\_service\_account\_json

```python theme={null}
def read_gcp_service_account_json(context_path: str,
                                  path_or_content: Union[str, dict]) -> str
```

Read GCP service account JSON from a file or object.

**Arguments**:

* `context_path`: Base directory for resolving relative file paths
* `path_or_content`: Either a path to a JSON file or a service account object

**Returns**:

Service account JSON as a string