Building

Build custom templates with pre-configured environments, dependencies, and settings. Templates allow you to create reusable sandbox configurations.

Prerequisites

Before you begin, make sure you have:

HopX API key - Get one from console.hopx.dev or see [API key Management](/API key)
Understanding of templates - Familiarity with Listing Templates is helpful
Base image or template - Decide on a base image (Python, Node.js, Ubuntu, etc.)
Dependencies list - Know what packages or tools you want pre-installed

Overview

Building templates enables you to:

Pre-install packages and dependencies
Configure environment variables
Set up working directories and users
Create reusable sandbox configurations
Optimize sandbox creation time

Template building is an async operation that can take several minutes. The build process includes uploading files, executing build steps, and waiting for template activation.

Basic Template Building

Create a simple template from a base image:

Python
JavaScript

from hopx_ai.template import Template, BuildOptions
import os

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

# Add build steps
template.run_cmd("pip install numpy pandas matplotlib")

# Build template
options = BuildOptions(
    name="my-python-template",
    api_key=os.getenv("HOPX_API_KEY"),
    cpu=2,
    memory=2048,
    disk_gb=10,
    context_path=os.getcwd()  # Required: working directory for file operations
)

result = await Template.build(template, options)
print(f"Template built: {result.template_id}")
print(f"Build ID: {result.build_id}")

// Note: JavaScript SDK template building may have different API
// This is a conceptual example based on Python SDK patterns

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

// Create template from base image
const template = new Template('python:3.11-slim');

// Add build steps
template.runCmd('pip install numpy pandas matplotlib');

// Build template
const options = new BuildOptions({
  name: 'my-python-template',
  apiKey: process.env.HOPX_API_KEY,
  cpu: 2,
  memory: 2048,
  diskGb: 10
});

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

Using Base Image Helpers

Use convenient base image helpers:

Python
JavaScript

from hopx_ai.template import Template, BuildOptions
import os

# From Ubuntu
template = Template().from_ubuntu_image("22.04")
template.apt_install("curl", "git", "vim")

# From Python
template = Template().from_python_image("3.11")
template.pip_install("numpy", "pandas")

# From Node.js
template = Template().from_node_image("20")
template.npm_install("typescript", "tsx")

# Build
options = BuildOptions(
    name="my-template",
    api_key=os.getenv("HOPX_API_KEY"),
    context_path=os.getcwd()
)
result = await Template.build(template, options)

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

// From Ubuntu
const template = new Template().fromUbuntuImage('22.04');
template.aptInstall('curl', 'git', 'vim');

// From Python
const template2 = new Template().fromPythonImage('3.11');
template2.pipInstall('numpy', 'pandas');

// From Node.js
const template3 = new Template().fromNodeImage('20');
template3.npmInstall('typescript', 'tsx');

Complete Template Example

Build a complete template with multiple steps:

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

# Install system packages
template.apt_install("curl", "git", "build-essential")

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

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

# Set environment variables
template.set_env("FLASK_ENV", "production")
template.set_env("PORT", "8000")

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

# Set start command and 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 template
options = BuildOptions(
    name="flask-app-template",
    api_key=os.getenv("HOPX_API_KEY"),
    cpu=2,
    memory=2048,
    disk_gb=10,
    context_path=os.getcwd()  # Required for file operations
)

result = await Template.build(template, options)
print(f"✅ Template built: {result.template_id}")
print(f"   Build ID: {result.build_id}")
print(f"   Duration: {result.duration}s")

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

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

// Install system packages
template.aptInstall('curl', 'git', 'build-essential');

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

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

// Set environment variables
template.setEnv('FLASK_ENV', 'production');
template.setEnv('PORT', '8000');

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

// Build template
const options = new BuildOptions({
  name: 'flask-app-template',
  apiKey: process.env.HOPX_API_KEY,
  cpu: 2,
  memory: 2048,
  diskGb: 10
});

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

Build Options

Configure build options:

Python
JavaScript

from hopx_ai.template import BuildOptions
import os

options = BuildOptions(
    name="my-template",              # Required: Template name
    api_key=os.getenv("HOPX_API_KEY"),  # Required: API key
    cpu=2,                           # CPU cores (default: 2)
    memory=2048,                     # Memory in MB (default: 2048)
    disk_gb=10,                      # Disk in GB (default: 10)
    context_path=os.getcwd(),        # Required: Working directory for file operations
    skip_cache=False,                # Skip build cache (default: False)
    update=False,                    # Update existing template (default: False)
    template_activation_timeout=2700  # Max wait for activation in seconds (default: 2700)
)

# With progress callbacks
def on_progress(progress: int):
    print(f"Build progress: {progress}%")

def on_log(log_entry: dict):
    print(f"[{log_entry['level']}] {log_entry['message']}")

options.on_progress = on_progress
options.on_log = on_log

// Conceptual example
const options = new BuildOptions({
  name: 'my-template',              // Required: Template name
  apiKey: process.env.HOPX_API_KEY, // Required: API key
  cpu: 2,                           // CPU cores (default: 2)
  memory: 2048,                     // Memory in MB (default: 2048)
  diskGb: 10,                       // Disk in GB (default: 10)
  skipCache: false,                 // Skip build cache (default: false)
  update: false,                    // Update existing template (default: false)
  templateActivationTimeout: 2700,  // Max wait for activation in seconds
  onProgress: (progress) => {
    console.log(`Build progress: ${progress}%`);
  },
  onLog: (logEntry) => {
    console.log(`[${logEntry.level}] ${logEntry.message}`);
  }
});

Build Result and Logs

Access build results and logs:

Python
JavaScript

from hopx_ai.template import Template, BuildOptions
import os

# Build template
template = Template()
template.from_python_image("3.11-slim")
template.pip_install("numpy")

options = BuildOptions(
    name="test-template",
    api_key=os.getenv("HOPX_API_KEY"),
    context_path=os.getcwd()
)

result = await Template.build(template, options)

# Access build information
print(f"Build ID: {result.build_id}")
print(f"Template ID: {result.template_id}")
print(f"Duration: {result.duration}s")

# Get build logs
logs = await result.get_logs()
print(f"Logs:\n{logs.logs}")

# Poll for new logs
if not logs.complete:
    new_logs = await result.get_logs(offset=logs.offset)
    print(f"New logs:\n{new_logs.logs}")

// Conceptual example
const result = await Template.build(template, options);

// Access build information
console.log(`Build ID: ${result.buildId}`);
console.log(`Template ID: ${result.templateId}`);
console.log(`Duration: ${result.duration}s`);

// Get build logs
const logs = await result.getLogs();
console.log(`Logs:\n${logs.logs}`);

// Poll for new logs
if (!logs.complete) {
  const newLogs = await result.getLogs({ offset: logs.offset });
  console.log(`New logs:\n${newLogs.logs}`);
}

Best Practices

1. Start with Base Images

Use base image helpers (from_python_image, from_node_image) for common environments.

2. Chain Operations

Use fluent API to chain operations for readable template definitions.

3. Set Resources Appropriately

Configure CPU, memory, and disk based on your application needs.

4. Use Ready Checks

Set ready checks for services that need to be ready before sandbox is usable.

5. Monitor Build Progress

Use progress and log callbacks to monitor long-running builds.

Listing Templates - List available templates
Getting Template Details - View template information
Template Configuration - Configure template resources and steps
API: POST /v1/templates/build - Control Plane API endpoint
CLI Template Commands - Template management from CLI

Next Steps

Learn about Template Configuration for advanced setup
Explore Template Caching for build optimization
Review Listing Templates to see your built templates

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Prerequisites

Overview

Basic Template Building

Using Base Image Helpers

Complete Template Example

Build Options

Build Result and Logs

Best Practices

Next Steps

​Prerequisites

​Overview

​Basic Template Building

​Using Base Image Helpers

​Complete Template Example

​Build Options

​Build Result and Logs

​Best Practices

​Related

​Next Steps

Prerequisites

Overview

Basic Template Building

Using Base Image Helpers

Complete Template Example

Build Options

Build Result and Logs

Best Practices

Related

Next Steps