Skip to main content
List and filter your sandboxes to find existing environments, monitor their status, and manage multiple sandboxes efficiently.

​
Prerequisites

Before you begin, make sure you have:
  • HopX API key - Get one from console.hopx.dev or see [API key Management](/API key)
  • SDK installed - Python SDK (pip install hopx-ai) or JavaScript SDK (npm install @hopx-ai/sdk)
  • At least one sandbox - You should have created at least one sandbox (see Creating Sandboxes)

​
Basic Listing

List all your sandboxes:
  • Python
  • JavaScript
from hopx_ai import Sandbox

# List all sandboxes
sandboxes = Sandbox.list()

print(f"Found {len(sandboxes)} sandboxes")
for sandbox in sandboxes:
    info = sandbox.get_info()
    print(f"{sandbox.sandbox_id}: {info.status}")
Expected Output:
Found 3 sandboxes
sandbox_abc123xyz: running
sandbox_def456uvw: paused
sandbox_ghi789rst: running

​
Filtering by Status

Filter sandboxes by their current status:
  • Python
  • JavaScript
from hopx_ai import Sandbox

# List only running sandboxes
running = Sandbox.list(status="running")
print(f"Running sandboxes: {len(running)}")

# List paused sandboxes
paused = Sandbox.list(status="paused")
print(f"Paused sandboxes: {len(paused)}")
Expected Output:
Running sandboxes: 2
Paused sandboxes: 1

​
Combining Filters

Combine multiple filters:
  • Python
  • JavaScript
from hopx_ai import Sandbox

# List running sandboxes in EU region
running_eu = Sandbox.list(status="running", region="eu-west")
print(f"Running EU sandboxes: {len(running_eu)}")

# List with limit
limited = Sandbox.list(status="running", limit=10)
print(f"First 10 running sandboxes: {len(limited)}")

​
Lazy Iteration (Python)

For better memory usage with many sandboxes, use the iterator:
  • Python
from hopx_ai import Sandbox

found_it_flag = False

# Lazy loading - fetches pages as needed
for sandbox in Sandbox.iter(status="running"):
    info = sandbox.get_info()
    print(f"{sandbox.sandbox_id}: {info.public_host}")
    
    # Can break early without fetching remaining pages
    if found_it_flag:
        break
The iter() method is more memory-efficient for large numbers of sandboxes because it fetches pages on-demand rather than loading all sandboxes into memory at once.

​
Getting Detailed Information

Get detailed information for each sandbox:
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandboxes = Sandbox.list(status="running")

for sandbox in sandboxes:
    info = sandbox.get_info()
    print(f"\nSandbox: {sandbox.sandbox_id}")
    print(f"  Status: {info.status}")
    print(f"  Template: {info.template_name}")
    print(f"  URL: {info.public_host}")
    print(f"  Resources: {info.vcpu} vCPU, {info.memory_mb}MB RAM")
    print(f"  Internet: {info.internet_access}")
    if info.expires_at:
        print(f"  Expires: {info.expires_at}")

​
Common Use Cases

​
Find a Specific Sandbox

  • Python
  • JavaScript
from hopx_ai import Sandbox

# Find sandbox by ID pattern
sandboxes = Sandbox.list()
target_id = "1763309903rt5vs4lm"

for sandbox in sandboxes:
    if sandbox.sandbox_id == target_id:
        print(f"Found: {sandbox.sandbox_id}")
        info = sandbox.get_info()
        print(f"Status: {info.status}")
        break

​
Count Sandboxes by Status

  • Python
  • JavaScript
from hopx_ai import Sandbox
from collections import Counter

# Count sandboxes by status
sandboxes = Sandbox.list()
status_counts = Counter(sb.get_info().status for sb in sandboxes)

print("Sandbox status summary:")
for status, count in status_counts.items():
    print(f"  {status}: {count}")

​
Clean Up Old Sandboxes

  • Python
  • JavaScript
from hopx_ai import Sandbox
from datetime import datetime, timedelta

# Find and clean up sandboxes older than 1 hour
sandboxes = Sandbox.list()
cutoff = datetime.now() - timedelta(hours=1)

for sandbox in sandboxes:
    info = sandbox.get_info()
    created = datetime.fromisoformat(info.created_at.replace('Z', '+00:00'))
    
    if created < cutoff:
        print(f"Cleaning up old sandbox: {sandbox.sandbox_id}")
        sandbox.kill()

​
API Direct Access

You can also list sandboxes using direct API calls: 
# List all sandboxes
curl https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer your-API key"

# Filter by status
curl "https://api.hopx.dev/v1/sandboxes?status=running" \
  -H "Authorization: Bearer your-API key"

# Filter by region
curl "https://api.hopx.dev/v1/sandboxes?region=eu-west" \
  -H "Authorization: Bearer your-API key"

# Combine filters
curl "https://api.hopx.dev/v1/sandboxes?status=running&region=us-east&limit=10" \
  -H "Authorization: Bearer your-API key"

​
Implementation

​
Next Steps