Configuration

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

// Conceptual example
const options = new BuildOptions({
  name: 'my-template',
  apiKey: process.env.HOPX_API_KEY,
  cpu: 4,              // 4 vCPU cores
  memory: 4096,        // 4GB RAM
  diskGb: 20           // 20GB disk
});

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"))

// Conceptual example
const template = new Template('python:3.11-slim');

// Run commands
template.runCmd('apt-get update');
template.runCmd('apt-get install -y git curl');

// Install packages
template.aptInstall('vim', 'nano');
template.pipInstall('numpy', 'pandas');
template.npmInstall('typescript', 'tsx');

// Set working directory
template.setWorkdir('/app');

// Set user
template.setUser('appuser');

// Set environment variables
template.setEnv('NODE_ENV', 'production');
template.setEnv('DEBUG', 'false');

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)
)

// Conceptual example
import { waitForPort, waitForUrl } from '@hopx-ai/sdk';

const template = new Template('python:3.11-slim');
template.pipInstall('flask', 'gunicorn');

// Start command with port ready check
template.setStartCmd(
  'gunicorn -w 4 -b 0.0.0.0:8000 app:app',
  waitForPort(8000, { timeout: 30000 })
);

// Wait for URL
template.setStartCmd(
  'python app.py',
  waitForUrl('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/

// Conceptual example
const template = new Template('python:3.11-slim');

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

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}")

// Conceptual example
import { Template, BuildOptions, waitForPort } from '@hopx-ai/sdk';

const template = new Template('python:3.11-slim');

// System packages
template.aptInstall('curl', 'git', 'build-essential', 'postgresql-client');

// Working directory
template.setWorkdir('/app');

// Python packages
template.pipInstall('flask', 'gunicorn', 'psycopg2', 'redis');

// Environment variables
template.setEnv('FLASK_ENV', 'production');
template.setEnv('DATABASE_URL', 'postgresql://localhost/db');
template.setEnv('REDIS_URL', 'redis://localhost:6379');

// Expose ports
template.expose(8000);

// Start command with ready check
template.setStartCmd(
  'gunicorn -w 4 -b 0.0.0.0:8000 app:app',
  waitForPort(8000, { timeout: 30000 })
);

// Build with resource configuration
const options = new BuildOptions({
  name: 'flask-production-template',
  apiKey: process.env.HOPX_API_KEY,
  cpu: 4,
  memory: 4096,
  diskGb: 20
});

const result = await Template.build(template, options);
console.log(`Template configured and built: ${result.templateId}`);

Best Practices

1. Configure Resources First

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

2. Order Build Steps

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

3. Use Ready Checks

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

4. Set Environment Variables

Configure environment variables during template build for consistency.

5. Expose Required Ports

Expose all ports your application needs to be accessible.

Building Templates - Build custom templates
Listing Templates - List available templates
Getting Template Details - View template information
Creating Sandboxes - Create sandboxes from templates
CLI Template Commands - Template management from CLI

Next Steps

Learn about Building Templates to create templates
Explore Template Caching for build optimization
Review Getting Template Details to verify configuration

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Prerequisites

Overview

Resource Configuration

Build Steps

Start Command and Ready Checks

Port Exposure

Complete Configuration Example

Best Practices

Next Steps

​Prerequisites

​Overview

​Resource Configuration

​Build Steps

​Start Command and Ready Checks

​Port Exposure

​Complete Configuration Example

​Best Practices

​Related

​Next Steps

Prerequisites

Overview

Resource Configuration

Build Steps

Start Command and Ready Checks

Port Exposure

Complete Configuration Example

Best Practices

Related

Next Steps