> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Listing

> List available HopX sandbox templates and view their configurations. Discover pre-built templates for Python, JavaScript, Ubuntu, and other environments. Learn how to filter templates by category, language, or features, view template details, and choose the right template for your use case. Includes Python and JavaScript SDK examples and REST API endpoints.

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

<Note>
  Templates include both public templates (available to all users) and organization-specific templates (custom templates you've built).
</Note>

## List All Templates

Get a list of all available templates:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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}`);
      }
    }
    ```
  </Tab>
</Tabs>

## Filter by Category

Filter templates by category:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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)}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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}`);
    ```
  </Tab>
</Tabs>

## Filter by Language

Filter templates by programming language:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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}`);
    }
    ```
  </Tab>
</Tabs>

## Template Information

Access template details from the list:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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}`);
    }
    ```
  </Tab>
</Tabs>

## Find Template by Name

Search for a specific template:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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');
    }
    ```
  </Tab>
</Tabs>

## Complete Example

Here's a complete example showing template discovery:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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`);
      }
    }
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="1. List Before Creating">
    Always list templates first to discover available options before creating sandboxes.
  </Step>

  <Step title="2. Filter by Use Case">
    Use category and language filters to narrow down templates relevant to your needs.
  </Step>

  <Step title="3. Check Resources">
    Review default resources (vCPU, memory, disk) to ensure they meet your requirements.
  </Step>

  <Step title="4. Verify Status">
    Check template status (active, building, etc.) before using templates.
  </Step>

  <Step title="5. Use Template Names">
    Use template names (not IDs) when creating sandboxes for better readability.
  </Step>
</Steps>

## Related

* **[Getting Template Details](/core-concepts/templates/getting-details)** - Get detailed template information
* **[Creating Sandboxes](/core-concepts/sandboxes/creating)** - Create sandboxes from templates
* **SDK**: [Sandbox.list\_templates()](/sdk/python/sandbox#list_templates) - Python SDK method
* **API**: [GET /v1/templates](/api/control-plane/list-templates) - Control Plane API endpoint
* [CLI Template Commands](/cli/commands/template) - Template management from CLI

## Next Steps

* Learn about [Getting Template Details](/core-concepts/templates/getting-details) for complete template information
* Explore [Building Templates](/core-concepts/templates/building) to create custom templates
* Review [Template Configuration](/core-concepts/templates/configuration) for advanced setup