Skip to main content
Configure templates with resources, build steps, commands, environment variables, and ready checks. Template configuration determines the final sandbox environment.

​
Prerequisites

Before you begin, make sure you have:
  • Understanding of template building - Familiarity with Building Templates is required
  • Template builder SDK - Python SDK with template builder (from hopx_ai.template import Template)
  • Resource requirements - Know your CPU, memory, and disk requirements
  • Build steps - Plan your installation commands and file operations

​
Overview

Template configuration includes:
  • Resource specifications (CPU, memory, disk)
  • Build steps (commands, file operations)
  • Environment variables
  • Working directories and users
  • Start commands and ready checks
  • Port exposure and health checks
Template configuration is set during template building. Once built, templates are immutable - create a new template to change configuration.

​
Resource Configuration

Configure template resources:
  • Python
  • JavaScript
from hopx_ai.template import BuildOptions
import os

# Configure resources in BuildOptions
options = BuildOptions(
    name="my-template",
    api_key=os.getenv("HOPX_API_KEY"),
    cpu=4,              # 4 vCPU cores
    memory=4096,         # 4GB RAM
    disk_gb=20,         # 20GB disk
    context_path=os.getcwd()  # Required: Working directory
)

# Resource limits depend on your plan
# Typical ranges:
# - CPU: 1-64 cores
# - Memory: 512MB-64GB
# - Disk: 1GB-250GB

​
Build Steps

Configure build steps for template:
  • Python
  • JavaScript
from hopx_ai.template import Template

template = Template()
template.from_python_image("3.11-slim")

# Run commands
template.run_cmd("apt-get update")
template.run_cmd("apt-get install -y git curl")

# Install packages (convenience methods)
template.apt_install("vim", "nano")
template.pip_install("numpy", "pandas")
template.npm_install("typescript", "tsx")

# Set working directory
template.set_workdir("/app")

# Set user
template.set_user("appuser")

# Set environment variables
template.set_env("NODE_ENV", "production")
template.set_env("DEBUG", "false")

# Copy files (requires file upload)
# template.copy("/local/src", "/app", options=CopyOptions(owner="appuser"))

​
Start Command and Ready Checks

Configure start command and ready checks:
  • Python
  • JavaScript
from hopx_ai.template import Template
from hopx_ai.template.ready_checks import (
    wait_for_port,
    wait_for_url,
    wait_for_file,
    wait_for_process,
    wait_for_command
)

template = Template()
template.from_python_image("3.11-slim")
template.pip_install("flask", "gunicorn")

# Start command with port ready check
template.set_start_cmd(
    "gunicorn -w 4 -b 0.0.0.0:8000 app:app",
    ready=wait_for_port(8000, timeout=30000)
)

# Alternative ready checks
# Wait for URL
template.set_start_cmd(
    "python app.py",
    ready=wait_for_url("http://localhost:8000/health", timeout=30000)
)

# Wait for file
template.set_start_cmd(
    "python app.py",
    ready=wait_for_file("/app/ready.txt", timeout=30000)
)

# Wait for process
template.set_start_cmd(
    "python app.py",
    ready=wait_for_process("python", timeout=30000)
)

# Wait for command
template.set_start_cmd(
    "python app.py",
    ready=wait_for_command("curl -f http://localhost:8000/health", timeout=30000)
)

​
Port Exposure

Expose ports for services:
  • Python
  • JavaScript
from hopx_ai.template import Template

template = Template()
template.from_python_image("3.11-slim")

# Expose ports
template.expose(8000)   # HTTP server
template.expose(5432)  # PostgreSQL
template.expose(6379)  # Redis

# Ports are automatically exposed when sandbox is created
# Access via: https://{port}-{sandbox_id}.{region}.vms.hopx.dev/

​
Complete Configuration Example

Here’s a complete template configuration:
  • Python
  • JavaScript
from hopx_ai.template import Template, BuildOptions
from hopx_ai.template.ready_checks import wait_for_port
import os

# Create template
template = Template()
template.from_python_image("3.11-slim")

# System packages
template.apt_install("curl", "git", "build-essential", "postgresql-client")

# Working directory
template.set_workdir("/app")

# Python packages
template.pip_install("flask", "gunicorn", "psycopg2", "redis")

# Environment variables
template.set_env("FLASK_ENV", "production")
template.set_env("DATABASE_URL", "postgresql://localhost/db")
template.set_env("REDIS_URL", "redis://localhost:6379")

# Expose ports
template.expose(8000)

# Start command with ready check
template.set_start_cmd(
    "gunicorn -w 4 -b 0.0.0.0:8000 app:app",
    ready=wait_for_port(8000, timeout=30000)
)

# Build with resource configuration
options = BuildOptions(
    name="flask-production-template",
    api_key=os.getenv("HOPX_API_KEY"),
    cpu=4,
    memory=4096,
    disk_gb=20,
    context_path=os.getcwd()
)

result = await Template.build(template, options)
print(f"Template configured and built: {result.template_id}")

​
Best Practices

1

1. Configure Resources First

Set appropriate CPU, memory, and disk based on your application requirements.
2

2. Order Build Steps

Order build steps logically: system packages → language packages → application setup.
3

3. Use Ready Checks

Always set ready checks for services that need to be ready before use.
4

4. Set Environment Variables

Configure environment variables during template build for consistency.
5

5. Expose Required Ports

Expose all ports your application needs to be accessible.

​
Next Steps