Skip to main content
Learn how to build and use custom templates to create sandboxes with your preferred tools, packages, and configurations pre-installed.

​
Overview

Custom templates allow you to:
  • Pre-install packages and dependencies
  • Configure environment variables
  • Set up development tools
  • Create reusable environments
  • Reduce setup time

​
Prerequisites

  • API key configured (see Authentication)
  • Understanding of Docker or containerization concepts
  • Basic knowledge of template building
Custom template building requires API access. Check the API Reference for template building endpoints.

​
Understanding Templates

Templates are pre-configured VM images that define:
  • Base operating system
  • Pre-installed packages
  • Environment variables
  • Default configurations
  • Available tools

​
Building Custom Templates

​
Step 1: Define Template Steps

Templates are built using a step-based approach:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Template
from hopx_ai.template.types import BuildOptions

# Create template with fluent API
template = (
    Template()
    .from_ubuntu_image("22.04")
    .run_cmd("apt-get update && apt-get install -y git")
    .run_cmd("pip install scikit-learn tensorflow torch")
    .set_env("ML_ENV", "production")
    .set_workdir("/workspace")
)

# Build template
result = await Template.build(
    template,
    BuildOptions(
        alias="my-custom-template",
        api_key="hopx_live_...",
        cpu=2,
        memory=2048,
        disk_gb=10
    )
)

print(f"Template created: {result.template_id}")

​
Step 2: Template Building Patterns

template.pip_install("pandas", "numpy", "matplotlib", "scikit-learn")

template.run_cmd("npm install -g typescript ts-node")
template.npm_install("express", "axios")

# Copy configuration files
template.copy("config.json", "/workspace/config.json")
template.copy("scripts/", "/workspace/scripts/")

template.set_env("API_URL", "https://api.example.com")
template.set_env("DEBUG", "false")

template.set_workdir("/workspace/project")

​
Example: ML Template

Create a template for machine learning workloads:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Template, Sandbox
from hopx_ai.template.types import BuildOptions
import os

async def create_ml_template():
    """Create a template optimized for ML workloads"""
    # Define template with fluent API
    template = (
        Template()
        .from_ubuntu_image("22.04")
        .apt_install("python3-dev", "build-essential", "libblas-dev", "liblapack-dev")
        .pip_install(
            "numpy==1.24.3",
            "pandas==2.0.3",
            "scikit-learn==1.3.0",
            "tensorflow==2.13.0",
            "torch==2.0.1",
            "matplotlib==3.7.2",
            "seaborn==0.12.2",
            "jupyter==1.0.0"
        )
        .set_env("ML_ENV", "production")
        .set_env("OMP_NUM_THREADS", "4")
        .set_workdir("/workspace")
    )
    
    # Build template
    result = await Template.build(
        template,
        BuildOptions(
            alias="ml-template",
            api_key=os.getenv("HOPX_API_KEY"),
            cpu=4,
            memory=8192,
            disk_gb=20
        )
    )
    
    return result.template_id

# Build and use template
template_id = await create_ml_template()

# Use the template (use the template alias as a string)
sandbox = Sandbox.create(template="ml-template")
try:
result = sandbox.run_code("""
import tensorflow as tf
import torch
print(f"TensorFlow: {tf.__version__}")
print(f"PyTorch: {torch.__version__}")
""")
    print(result.stdout)
finally:
    sandbox.kill()

​
Example: Web Development Template

Create a template for web development:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Template
from hopx_ai.template.types import BuildOptions
import os

async def create_web_template():
    """Create a template for web development"""
    # Define template with fluent API
    template = (
        Template()
        .from_ubuntu_image("22.04")
        .run_cmd("curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && apt-get install -y nodejs")
        .run_cmd("npm install -g typescript ts-node nodemon")
        .npm_install("express", "axios", "dotenv", "cors")
        .set_env("NODE_ENV", "development")
        .set_env("PORT", "3000")
    )
    
    # Build template
    result = await Template.build(
        template,
        BuildOptions(
            alias="web-dev-template",
            api_key=os.getenv("HOPX_API_KEY"),
            cpu=2,
            memory=2048,
            disk_gb=10
        )
    )
    
    return result.template_id

template_id = await create_web_template()

​
Using Custom Templates

Once built, use your custom templates like any other:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Use your custom template
sandbox = Sandbox.create(template="my-custom-template")
try:
# Everything is pre-configured
result = sandbox.run_code("""
# Your code here - packages already installed
import my_package
my_package.doSomething()
""")
    print(result.stdout)
finally:
    sandbox.kill()

​
Best Practices

Pin package versions for reproducibility:
template.pip_install("pandas==2.0.3", "numpy==1.24.3")
Combine commands to reduce build time:
# ✅ Good: Combined commands
template.run_cmd("apt-get update && apt-get install -y package1 package2")

# ❌ Bad: Separate commands
# template.run_cmd("apt-get update")
# template.run_cmd("apt-get install -y package1")
# template.run_cmd("apt-get install -y package2")
Set appropriate resources for your template:
result = await Template.build(
    template,
    BuildOptions(
        alias="ml-template",
        api_key=api_key,
        cpu=4,
        memory=8192,
        disk_gb=50
    )
)
Use descriptive alias names for clarity:
result = await Template.build(
    template,
    BuildOptions(
        alias="data-science-pandas-numpy",
        api_key=api_key
    )
)

​
Next Steps

Templates Overview

Learn more about templates

API Reference

Template building API reference

Cost Optimization

Optimize template costs

Performance

Optimize template performance