> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Template Builder

> Fluent API for building custom sandbox templates in the HopX Python SDK. Create custom templates from Docker images, configure resources, add build steps, and install dependencies using a fluent builder pattern. Complete reference for TemplateBuilder class with code examples and template configuration options.

**Version:** 0.3.0\
**Last Verified:** 2025-01-27\
**Package:** `hopx-ai` on [PyPI](https://pypi.org/project/hopx-ai/)

## Overview

The `Template` class provides a fluent API for building custom sandbox templates. Use this to create reusable templates with specific configurations, dependencies, and ready checks.

Templates are built from base images and can include file copies, command execution, environment variables, port exposure, and ready checks.

## Import

```python theme={null}
from hopx_ai.template import Template
```

## Base Image Methods

### `from_ubuntu_image`

Start from Ubuntu base image.

```python theme={null}
Template.from_ubuntu_image(version) -> Template
```

**Parameters:**

* `version` (`str`): Ubuntu version (e.g., `"22.04"`)

**Returns:** `Template` - Template instance (fluent API)

**Expected Output:**

```
Template instance ready for configuration
```

***

### `from_python_image`

Start from Python base image.

```python theme={null}
Template.from_python_image(version) -> Template
```

**Parameters:**

* `version` (`str`): Python version (e.g., `"3.11"`)

**Expected Output:**

```
Template instance ready for configuration
```

***

### `from_node_image`

Start from Node.js base image.

```python theme={null}
Template.from_node_image(version) -> Template
```

**Parameters:**

* `version` (`str`): Node.js version (e.g., `"20"`)

**Expected Output:**

```
Template instance ready for configuration
```

***

### `from_image`

Start from any Docker image.

```python theme={null}
Template.from_image(image, auth=None) -> Template
```

**Parameters:**

* `image` (`str`): Docker image name
* `auth` (`Dict`, optional): Authentication credentials

**Expected Output:**

```
Template instance ready for configuration
```

***

## Configuration Methods

### `copy`

Copy files to the template.

```python theme={null}
Template.copy(src, dest, options=None) -> Template
```

**Parameters:**

* `src` (`str`): Source path
* `dest` (`str`): Destination path
* `options` (`Dict`, optional): Copy options

**Expected Output:**

```
Template instance (fluent API)
```

***

### `run`

Run command in template.

```python theme={null}
Template.run(command) -> Template
```

**Parameters:**

* `command` (`str`): Command to execute

**Expected Output:**

```
Template instance (fluent API)
```

**Example:**

```python theme={null}
Template.from_python_image("3.11").run("pip install requests")
```

***

### `env`

Set environment variable.

```python theme={null}
Template.env(key, value) -> Template
```

**Parameters:**

* `key` (`str`): Environment variable name
* `value` (`str`): Environment variable value

**Expected Output:**

```
Template instance (fluent API)
```

***

### `expose`

Expose port.

```python theme={null}
Template.expose(port) -> Template
```

**Parameters:**

* `port` (`int`): Port number to expose

**Expected Output:**

```
Template instance (fluent API)
```

***

### `workdir`

Set working directory.

```python theme={null}
Template.workdir(path) -> Template
```

**Parameters:**

* `path` (`str`): Working directory path

**Expected Output:**

```
Template instance (fluent API)
```

***

### `ready_check`

Set ready check.

```python theme={null}
Template.ready_check(check) -> Template
```

**Parameters:**

* `check` (ReadyCheck): Ready check object

**Expected Output:**

```
Template instance (fluent API)
```

See [Ready Checks](/sdk/python/ready-checks) for available ready checks.

***

### `start_cmd`

Set start command.

```python theme={null}
Template.start_cmd(command) -> Template
```

**Parameters:**

* `command` (`str`): Start command

**Expected Output:**

```
Template instance (fluent API)
```

***

## Building

### `build`

Build the template.

```python theme={null}
await Template.build(options=None) -> BuildResult
```

**Parameters:**

* `options` (`Dict`, optional): Build options

**Returns:** `BuildResult` - Build result with template ID and status

**Example:**

```python theme={null}
import asyncio

async def build_template():
    template = (
        Template
        .from_python_image("3.11")
        .run("pip install flask")
        .expose(5000)
        .start_cmd("python app.py")
    )
    
    result = await template.build()
    print(f"Template ID: {result.template_id}")

asyncio.run(build_template())
```

**Expected Output:**

```
Template ID: template_abc123xyz
```

***

## Examples

### Example 1: Simple Python Template

```python theme={null}
from hopx_ai.template import Template
import asyncio

async def main():
    template = (
        Template
        .from_python_image("3.11")
        .run("pip install requests pandas")
        .env("PYTHONUNBUFFERED", "1")
    )
    
    result = await template.build()
    print(f"Built template: {result.template_id}")

asyncio.run(main())
```

**Expected Output:**

```
Built template: template_abc123xyz
```

### Example 2: Web Server Template

```python theme={null}
from hopx_ai.template import Template, wait_for_port
import asyncio

async def main():
    template = (
        Template
        .from_node_image("20")
        .run("npm install express")
        .copy("./app.js", "/app/app.js")
        .expose(3000)
        .start_cmd("node /app/app.js")
        .ready_check(wait_for_port(3000))
    )
    
    result = await template.build()
    print(f"Web server template: {result.template_id}")

asyncio.run(main())
```

**Expected Output:**

```
Web server template: template_abc123xyz
```

***

## Related Classes

* **[Ready Checks](/sdk/python/ready-checks)** - Ready check utilities
* **[Sandbox](/sdk/python/sandbox)** - Use templates with `Sandbox.create(template=...)`

## See Also

* [Ready Checks](/sdk/python/ready-checks) - Learn about ready checks
* [Core Concepts: Templates](/core-concepts/templates) - Learn about templates

## Next Steps

Now that you understand template building, explore:

* [Ready Checks](/sdk/python/ready-checks) - Add readiness verification
* [Building Templates](/core-concepts/templates/building) - Learn template building concepts
* [Template Configuration](/core-concepts/templates/configuration) - Configure templates
* **[CLI Reference](/cli/introduction)** - Use HopX from the command line
* [Custom Templates](/cookbooks/advanced/custom-templates) - Build custom templates