Skip to main content
Version: 0.3.0
Last Verified: 2025-01-27
Package: hopx-ai on PyPI

​
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

from hopx_ai.template import Template

​
Base Image Methods

​
from_ubuntu_image

Start from Ubuntu base image. 
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. 
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. 
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. 
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. 
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. 
Template.run(command) -> Template
Parameters:
  • command (str): Command to execute
Expected Output: 
Template instance (fluent API)
Example: 
Template.from_python_image("3.11").run("pip install requests")

​
env

Set environment variable. 
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. 
Template.expose(port) -> Template
Parameters:
  • port (int): Port number to expose
Expected Output: 
Template instance (fluent API)

​
workdir

Set working directory. 
Template.workdir(path) -> Template
Parameters:
  • path (str): Working directory path
Expected Output: 
Template instance (fluent API)

​
ready_check

Set ready check. 
Template.ready_check(check) -> Template
Parameters:
  • check (ReadyCheck): Ready check object
Expected Output: 
Template instance (fluent API)
See Ready Checks for available ready checks.

​
start_cmd

Set start command. 
Template.start_cmd(command) -> Template
Parameters:
  • command (str): Start command
Expected Output: 
Template instance (fluent API)

​
Building

​
build

Build the template. 
await Template.build(options=None) -> BuildResult
Parameters:
  • options (Dict, optional): Build options
Returns: BuildResult - Build result with template ID and status Example: 
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

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

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
  • Ready Checks - Ready check utilities
  • Sandbox - Use templates with Sandbox.create(template=...)

​
See Also

​
Next Steps

Now that you understand template building, explore: