Skip to main content
This guide covers the fundamental operations for working with Hopx Sandboxes, including sandbox creation, connection, information retrieval, and proper cleanup patterns.

​
Creating a Sandbox

The simplest way to create a sandbox is with minimal configuration:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox
import os

API_KEY = os.getenv("HOPX_API_KEY")

# Create sandbox with minimal options
sandbox = Sandbox.create(
    template="code-interpreter",
    api_key=API_KEY
)

print(f"Sandbox ID: {sandbox.sandbox_id}")

# Get sandbox information
info = sandbox.get_info()
print(f"Status: {info.status}")
print(f"Agent URL: {info.public_host}")
print(f"Template: {info.template_name}")

# Cleanup
sandbox.kill()

​
Advanced Sandbox Creation

You can customize sandbox creation with additional options:
  • Python
  • JavaScript/TypeScript
sandbox = Sandbox.create(
    template="code-interpreter",
    api_key=API_KEY,
    timeout_seconds=600,  # 10 minute timeout
    env_vars={            # Pre-set environment variables
        "PYTHONPATH": "/workspace",
        "DEBUG": "true"
    }
)

# Get detailed info
info = sandbox.get_info()
if info.resources:
    print(f"vCPU: {info.resources.vcpu}")
    print(f"Memory: {info.resources.memory_mb}MB")

​
Automatic Cleanup with Context Managers

Always use context managers (Python) or try/finally blocks (JavaScript) to ensure proper cleanup:
  • Python
  • JavaScript/TypeScript
# ✅ GOOD: Context manager ensures cleanup
with Sandbox.create(template="code-interpreter", api_key=API_KEY) as sandbox:
    result = sandbox.run_code("print('Hello from sandbox!')")
    print(result.stdout)
# Sandbox automatically deleted here

# ❌ BAD: Manual cleanup (easy to forget)
sandbox = Sandbox.create(template="code-interpreter", api_key=API_KEY)
result = sandbox.run_code("print('Hello')")
# If an exception occurs, sandbox.kill() might not be called!
sandbox.kill()

​
Connecting to Existing Sandboxes

You can connect to an existing sandbox by its ID:
  • Python
  • JavaScript/TypeScript
# Create a sandbox
sandbox1 = Sandbox.create(template="code-interpreter", api_key=API_KEY)
sandbox_id = sandbox1.sandbox_id
print(f"Created sandbox: {sandbox_id}")

# Connect to the same sandbox by ID
sandbox2 = Sandbox.connect(sandbox_id, api_key=API_KEY)
print(f"Connected to sandbox: {sandbox2.sandbox_id}")

# Verify they're the same
info1 = sandbox1.get_info()
info2 = sandbox2.get_info()
assert info1.public_host == info2.public_host
print("Same sandbox confirmed!")

sandbox1.kill()

​
Listing Sandboxes

List and filter your running sandboxes:
  • Python
  • JavaScript/TypeScript
# List all running sandboxes
sandboxes = Sandbox.list(
    api_key=API_KEY,
    status="running",
    limit=10
)

print(f"Found {len(sandboxes)} running sandbox(es)")

for sb in sandboxes:
    print(f"  ID: {sb.sandbox_id}")
    print(f"  Template: {sb.template_name}")
    print(f"  Status: {sb.status}")
    print()

​
Error Handling

Proper error handling is essential for production code:
  • Python
  • JavaScript/TypeScript
from hopx_ai.errors import (
    AuthenticationError,
    NotFoundError,
    ResourceLimitError,
    HopxError
)

try:
    sandbox = Sandbox.create(template="code-interpreter", api_key=API_KEY)
    
    # Try to get non-existent file
    try:
        content = sandbox.files.read("/non-existent-file.txt")
    except NotFoundError as e:
        print(f"File not found: {e.message}")
        print(f"Request ID: {e.request_id}")
    
    sandbox.kill()
    
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except ResourceLimitError as e:
    print(f"Resource limit exceeded: {e.message}")
except HopxError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")
    print(f"Request ID: {e.request_id}")

​
Next Steps

Code Execution

Learn how to execute code in sandboxes

File Operations

Upload, download, and manage files

Best Practices

Production-ready patterns and recommendations

SDK Reference

Complete SDK API reference