Listing

List all available templates to discover pre-configured environments for your sandboxes. Templates define the base system, default resources, and pre-installed packages.

Overview

Listing templates helps you:

Discover available pre-configured environments
Find templates by category or language
Compare template resources and features
Choose the right template for your use case

Templates include both public templates (available to all users) and organization-specific templates (custom templates you’ve built).

List All Templates

Get a list of all available templates:

Python
JavaScript

from hopx_ai import Sandbox

# List all templates
templates = Sandbox.list_templates()

print(f"Found {len(templates)} templates:")
for template in templates:
    print(f"  - {template.name}: {template.display_name}")
    if template.description:
        print(f"    {template.description}")

import { Sandbox } from '@hopx-ai/sdk';

// List all templates
const templates = await Sandbox.listTemplates();

console.log(`Found ${templates.length} templates:`);
for (const template of templates) {
  console.log(`  - ${template.name}: ${template.displayName}`);
  if (template.description) {
    console.log(`    ${template.description}`);
  }
}

Filter by Category

Filter templates by category:

Python
JavaScript

from hopx_ai import Sandbox

# Filter by category
dev_templates = Sandbox.list_templates(category="development")
print(f"Development templates: {len(dev_templates)}")

infra_templates = Sandbox.list_templates(category="infrastructure")
print(f"Infrastructure templates: {len(infra_templates)}")

os_templates = Sandbox.list_templates(category="operating-system")
print(f"OS templates: {len(os_templates)}")

import { Sandbox } from '@hopx-ai/sdk';

// Filter by category
const devTemplates = await Sandbox.listTemplates({ category: 'development' });
console.log(`Development templates: ${devTemplates.length}`);

const infraTemplates = await Sandbox.listTemplates({ category: 'infrastructure' });
console.log(`Infrastructure templates: ${infraTemplates.length}`);

const osTemplates = await Sandbox.listTemplates({ category: 'operating-system' });
console.log(`OS templates: ${osTemplates.length}`);

Filter by Language

Filter templates by programming language:

Python
JavaScript

from hopx_ai import Sandbox

# Filter by language
python_templates = Sandbox.list_templates(language="python")
print(f"Python templates: {len(python_templates)}")
for t in python_templates:
    print(f"  - {t.name}: {t.display_name}")

nodejs_templates = Sandbox.list_templates(language="nodejs")
print(f"\nNode.js templates: {len(nodejs_templates)}")
for t in nodejs_templates:
    print(f"  - {t.name}: {t.display_name}")

import { Sandbox } from '@hopx-ai/sdk';

// Filter by language
const pythonTemplates = await Sandbox.listTemplates({ language: 'python' });
console.log(`Python templates: ${pythonTemplates.length}`);
for (const t of pythonTemplates) {
  console.log(`  - ${t.name}: ${t.displayName}`);
}

const nodejsTemplates = await Sandbox.listTemplates({ language: 'nodejs' });
console.log(`\nNode.js templates: ${nodejsTemplates.length}`);
for (const t of nodejsTemplates) {
  console.log(`  - ${t.name}: ${t.displayName}`);
}

Template Information

Access template details from the list:

Python
JavaScript

from hopx_ai import Sandbox

templates = Sandbox.list_templates()

for template in templates:
    print(f"\n{template.display_name} ({template.name})")
    print(f"  Category: {template.category}")
    print(f"  Language: {template.language or 'N/A'}")
    
    if template.default_resources:
        res = template.default_resources
        print(f"  Resources: {res.vcpu} vCPU, {res.memory_mb}MB RAM, {res.disk_gb}GB disk")
    
    if template.features:
        print(f"  Features: {', '.join(template.features)}")
    
    print(f"  Status: {template.status}")

import { Sandbox } from '@hopx-ai/sdk';

const templates = await Sandbox.listTemplates();

for (const template of templates) {
  console.log(`\n${template.displayName} (${template.name})`);
  console.log(`  Category: ${template.category}`);
  console.log(`  Language: ${template.language || 'N/A'}`);
  
  if (template.defaultResources) {
    const res = template.defaultResources;
    console.log(`  Resources: ${res.vcpu} vCPU, ${res.memoryMb}MB RAM, ${res.diskGb}GB disk`);
  }
  
  if (template.features) {
    console.log(`  Features: ${template.features.join(', ')}`);
  }
  
  console.log(`  Status: ${template.status}`);
}

Find Template by Name

Search for a specific template:

Python
JavaScript

from hopx_ai import Sandbox

# List all and find by name
templates = Sandbox.list_templates()

# Find specific template
code_interpreter = next(
    (t for t in templates if t.name == "code-interpreter"),
    None
)

if code_interpreter:
    print(f"Found: {code_interpreter.display_name}")
    print(f"Description: {code_interpreter.description}")
else:
    print("Template not found")

import { Sandbox } from '@hopx-ai/sdk';

// List all and find by name
const templates = await Sandbox.listTemplates();

// Find specific template
const codeInterpreter = templates.find(t => t.name === 'code-interpreter');

if (codeInterpreter) {
  console.log(`Found: ${codeInterpreter.displayName}`);
  console.log(`Description: ${codeInterpreter.description}`);
} else {
  console.log('Template not found');
}

Complete Example

Here’s a complete example showing template discovery:

Python
JavaScript

from hopx_ai import Sandbox

print("🔍 Discovering Templates\n")

# List all templates
all_templates = Sandbox.list_templates()
print(f"Total templates: {len(all_templates)}\n")

# Group by category
categories = {}
for template in all_templates:
    cat = template.category or "uncategorized"
    if cat not in categories:
        categories[cat] = []
    categories[cat].append(template)

# Display by category
for category, templates in categories.items():
    print(f"📁 {category.title()} ({len(templates)} templates)")
    for template in templates:
        print(f"  • {template.display_name}")
        if template.default_resources:
            res = template.default_resources
            print(f"    {res.vcpu}vCPU, {res.memory_mb}MB RAM")
    print()

# Find Python templates
python_templates = Sandbox.list_templates(language="python")
print(f"🐍 Python Templates: {len(python_templates)}")
for t in python_templates[:5]:  # Show first 5
    print(f"  - {t.name}: {t.display_name}")

# Find a specific template
code_interpreter = next(
    (t for t in all_templates if t.name == "code-interpreter"),
    None
)
if code_interpreter:
    print(f"\n✅ Found code-interpreter:")
    print(f"   {code_interpreter.description}")
    if code_interpreter.default_resources:
        res = code_interpreter.default_resources
        print(f"   Resources: {res.vcpu} vCPU, {res.memory_mb}MB RAM")

import { Sandbox } from '@hopx-ai/sdk';

console.log('🔍 Discovering Templates\n');

// List all templates
const allTemplates = await Sandbox.listTemplates();
console.log(`Total templates: ${allTemplates.length}\n`);

// Group by category
const categories = {};
for (const template of allTemplates) {
  const cat = template.category || 'uncategorized';
  if (!categories[cat]) {
    categories[cat] = [];
  }
  categories[cat].push(template);
}

// Display by category
for (const [category, templates] of Object.entries(categories)) {
  console.log(`📁 ${category.charAt(0).toUpperCase() + category.slice(1)} (${templates.length} templates)`);
  for (const template of templates) {
    console.log(`  • ${template.displayName}`);
    if (template.defaultResources) {
      const res = template.defaultResources;
      console.log(`    ${res.vcpu}vCPU, ${res.memoryMb}MB RAM`);
    }
  }
  console.log();
}

// Find Python templates
const pythonTemplates = await Sandbox.listTemplates({ language: 'python' });
console.log(`🐍 Python Templates: ${pythonTemplates.length}`);
for (const t of pythonTemplates.slice(0, 5)) {  // Show first 5
  console.log(`  - ${t.name}: ${t.displayName}`);
}

// Find a specific template
const codeInterpreter = allTemplates.find(t => t.name === 'code-interpreter');
if (codeInterpreter) {
  console.log(`\n✅ Found code-interpreter:`);
  console.log(`   ${codeInterpreter.description}`);
  if (codeInterpreter.defaultResources) {
    const res = codeInterpreter.defaultResources;
    console.log(`   Resources: ${res.vcpu} vCPU, ${res.memoryMb}MB RAM`);
  }
}

Best Practices

1. List Before Creating

Always list templates first to discover available options before creating sandboxes.

2. Filter by Use Case

Use category and language filters to narrow down templates relevant to your needs.

3. Check Resources

Review default resources (vCPU, memory, disk) to ensure they meet your requirements.

4. Verify Status

Check template status (active, building, etc.) before using templates.

5. Use Template Names

Use template names (not IDs) when creating sandboxes for better readability.

Getting Template Details - Get detailed template information
Creating Sandboxes - Create sandboxes from templates
SDK: Sandbox.list_templates() - Python SDK method
API: GET /v1/templates - Control Plane API endpoint
CLI Template Commands - Template management from CLI

Next Steps

Learn about Getting Template Details for complete template information
Explore Building Templates to create custom templates
Review Template Configuration for advanced setup

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

List All Templates

Filter by Category

Filter by Language

Template Information

Find Template by Name

Complete Example

Best Practices

Next Steps

​Overview

​List All Templates

​Filter by Category

​Filter by Language

​Template Information

​Find Template by Name

​Complete Example

​Best Practices

​Related

​Next Steps

Overview

List All Templates

Filter by Category

Filter by Language

Template Information

Find Template by Name

Complete Example

Best Practices

Related

Next Steps