Skip to main content
Sandbox resources (vCPU, memory, and disk) are automatically configured from templates. You cannot specify custom resources when creating a sandbox - resources are always loaded from the template you choose.

​
How Resources Work

When you create a sandbox from a template, the sandbox automatically gets the resources defined in that template:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Get template details to see its resources
template = Sandbox.get_template("code-interpreter")

if template.default_resources:
    print(f"vCPU: {template.default_resources.vcpu}")
    print(f"Memory: {template.default_resources.memory_mb} MB")
    print(f"Disk: {template.default_resources.disk_gb} GB")

# Create sandbox - resources come from template automatically
sandbox = Sandbox.create(template="code-interpreter")
# Resources are set from template, no need to specify them
Resources are always loaded from templates. To get different resources, choose a different template or create a custom template with your desired resource configuration.

​
Understanding Resource Types

​
vCPU (CPU Cores)

The number of virtual CPU cores determines how much parallel processing your sandbox can handle. Typical ranges:
  • 1-2 vCPU: Light workloads, simple scripts, basic data processing
  • 4-8 vCPU: Data analysis with Pandas, parallel processing, moderate ML workloads
  • 16+ vCPU: Heavy compute, ML training, large-scale data processing

​
Memory (RAM)

The amount of RAM determines how much data you can load into memory at once. Typical ranges:
  • 512 MB - 1 GB: Simple scripts, basic operations
  • 2-4 GB: Data analysis with Pandas, moderate datasets
  • 8-16 GB: Large datasets, ML models, complex computations
  • 32+ GB: Very large datasets, deep learning models

​
Disk

The disk size determines how much data you can store in the sandbox. Typical ranges:
  • 5-10 GB: Code execution only, small files
  • 20-50 GB: File processing, moderate datasets
  • 100+ GB: Large datasets, media files, extensive file operations

​
Viewing Template Resources

Before creating a sandbox, you can check what resources a template provides:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Get template details
template = Sandbox.get_template("code-interpreter")

print(f"Template: {template.display_name}")
print(f"Description: {template.description}")

if template.default_resources:
    print(f"\nDefault Resources:")
    print(f"  vCPU: {template.default_resources.vcpu}")
    print(f"  Memory: {template.default_resources.memory_mb} MB")
    print(f"  Disk: {template.default_resources.disk_gb} GB")

# Now create sandbox with these resources
sandbox = Sandbox.create(template="code-interpreter")
sandbox.kill()  # Cleanup

​
Choosing Templates Based on Resources

​
List All Templates

Discover available templates and their resources:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# List all templates
templates = Sandbox.list_templates()

for t in templates:
    print(f"{t.name}: {t.display_name}")
    if t.default_resources:
        print(f"  Resources: {t.default_resources.vcpu} vCPU, "
              f"{t.default_resources.memory_mb}MB RAM, "
              f"{t.default_resources.disk_gb}GB disk")
    print()

​
Filter Templates by Category

Find templates suitable for your workload:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Filter by category
dev_templates = Sandbox.list_templates(category="development")

# Filter by language
python_templates = Sandbox.list_templates(language="python")

# Find templates with specific resources
for t in Sandbox.list_templates():
    if t.default_resources:
        if t.default_resources.vcpu >= 4 and t.default_resources.memory_mb >= 4096:
            print(f"{t.name}: Good for data analysis")

​
Resource Recommendations by Workload

​
Lightweight Workload

For simple scripts and basic operations, choose templates with minimal resources:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Find lightweight templates
templates = Sandbox.list_templates()
for t in templates:
    if t.default_resources:
        if t.default_resources.vcpu <= 2 and t.default_resources.memory_mb <= 1024:
            print(f"{t.name}: Good for lightweight workloads")
            sandbox = Sandbox.create(template=t.name)
            # Use sandbox...
            sandbox.kill()
            break

​
Data Analysis Workload

For data analysis with Pandas and visualization, choose templates with 4+ vCPU and 4GB+ RAM:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Use code-interpreter template (typically has good resources for data analysis)
template = Sandbox.get_template("code-interpreter")
print(f"Resources: {template.default_resources.vcpu} vCPU, "
      f"{template.default_resources.memory_mb}MB RAM")

sandbox = Sandbox.create(template="code-interpreter")
# Perfect for data analysis
result = sandbox.run_code("""
import pandas as pd
import numpy as np
df = pd.DataFrame({'x': range(1000), 'y': np.random.randn(1000)})
print(df.describe())
""")
sandbox.kill()  # Cleanup

​
ML Training Workload

For machine learning training and large datasets, choose templates with 16+ vCPU and 16GB+ RAM:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Find high-resource templates
templates = Sandbox.list_templates()
for t in templates:
    if t.default_resources:
        if t.default_resources.vcpu >= 16 and t.default_resources.memory_mb >= 16384:
            print(f"{t.name}: Good for ML training")
            sandbox = Sandbox.create(template=t.name)
            # Use for ML training...
            sandbox.kill()
            break

​
Region Selection

You can specify a region when creating a sandbox to minimize latency:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Choose region closest to your users
sandbox = Sandbox.create(
    template="code-interpreter",
    region="us-west-2"  # Oregon, USA
)
sandbox.kill()  # Cleanup
Available regions:
  • us-west-2 (Oregon, USA)
  • us-east-1 (Virginia, USA)
  • eu-west-1 (Ireland, EU)
  • ap-southeast-1 (Singapore, APAC)
Choose the region closest to your users or data sources to minimize latency. Resources are still determined by the template, not the region.

​
Custom Templates for Custom Resources

If you need specific resource configurations that aren’t available in built-in templates, you can create a custom template:
  • Python
  • JavaScript/TypeScript
from hopx_ai.template import TemplateBuilder

# Create custom template with specific resources
builder = TemplateBuilder("my-custom-template")
builder.from_image("python:3.11")

# Build template with custom resources
result = builder.build(
    vcpu=8,           # 8 vCPU cores
    memory_mb=16384,  # 16 GB RAM
    disk_gb=100       # 100 GB disk
)

print(f"Template created: {result.template_id}")

# Now use this template
from hopx_ai import Sandbox
sandbox = Sandbox.create(template_id=result.template_id)
# Sandbox will have 8 vCPU, 16GB RAM, 100GB disk
sandbox.kill()  # Cleanup
See the Custom Templates guide for detailed instructions on creating templates with your desired resource configurations.

​
Cost Optimization Tips

Start with templates that have minimal resources and scale up if needed:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Start with lightweight template
templates = Sandbox.list_templates()
lightweight = next(t for t in templates 
                  if t.default_resources and 
                  t.default_resources.vcpu == 1)

sandbox = Sandbox.create(template=lightweight.name)
# Test your workload
# If you need more, switch to a higher-resource template
sandbox.kill()
Use metrics to understand your actual resource needs and choose appropriate templates:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Run your workload
sandbox.run_code("your_code_here")

# Check resource usage
metrics = sandbox.get_metrics()
print(f"CPU: {metrics.cpu_percent}%")
print(f"Memory: {metrics.memory_used_mb}/{metrics.memory_total_mb} MB")

# Use this info to choose the right template next time
sandbox.kill()
Select templates that match your workload requirements - don’t over-provision:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# For simple scripts, use minimal resources
# For data analysis, use code-interpreter
# For ML training, find high-resource templates

# List templates and their resources
templates = Sandbox.list_templates()
for t in templates:
    if t.default_resources:
        print(f"{t.name}: {t.default_resources.vcpu}vCPU, "
              f"{t.default_resources.memory_mb}MB")

​
Next Steps

Core Concepts

Back to Core Concepts overview

Templates

Learn about templates

Observability

Monitor resource usage

Custom Templates

Create custom templates