Listing

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

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

// List all sandboxes
const sandboxes = await Sandbox.list();

console.log(`Found ${sandboxes.length} sandboxes`);
for (const sandbox of sandboxes) {
  const info = await sandbox.getInfo();
  console.log(`${sandbox.sandboxId}: ${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

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

// List only running sandboxes
const running = await Sandbox.list({ status: 'running' });
console.log(`Running sandboxes: ${running.length}`);

// List paused sandboxes
const paused = await Sandbox.list({ status: 'paused' });
console.log(`Paused sandboxes: ${paused.length}`);

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)}")

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

// List running sandboxes in EU region
const runningEu = await Sandbox.list({
  status: 'running',
  region: 'eu-west'
});
console.log(`Running EU sandboxes: ${runningEu.length}`);

// List with limit
const limited = await Sandbox.list({
  status: 'running',
  limit: 10
});
console.log(`First 10 running sandboxes: ${limited.length}`);

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}")

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

const sandboxes = await Sandbox.list({ status: 'running' });

for (const sandbox of sandboxes) {
  const info = await sandbox.getInfo();
  console.log(`\nSandbox: ${sandbox.sandboxId}`);
  console.log(`  Status: ${info.status}`);
  console.log(`  Template: ${info.templateName}`);
  console.log(`  URL: ${info.publicHost}`);
  console.log(`  Resources: ${info.vcpu} vCPU, ${info.memoryMb}MB RAM`);
  console.log(`  Internet: ${info.internetAccess}`);
  if (info.expiresAt) {
    console.log(`  Expires: ${info.expiresAt}`);
  }
}

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

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

// Find sandbox by ID pattern
const sandboxes = await Sandbox.list();
const targetId = '1763309903rt5vs4lm';

for (const sandbox of sandboxes) {
  if (sandbox.sandboxId === targetId) {
    console.log(`Found: ${sandbox.sandboxId}`);
    const info = await sandbox.getInfo();
    console.log(`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}")

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

// Count sandboxes by status
const sandboxes = await Sandbox.list();
const statusCounts = {};

for (const sandbox of sandboxes) {
  const info = await sandbox.getInfo();
  statusCounts[info.status] = (statusCounts[info.status] || 0) + 1;
}

console.log('Sandbox status summary:');
for (const [status, count] of Object.entries(statusCounts)) {
  console.log(`  ${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()

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

// Find and clean up sandboxes older than 1 hour
const sandboxes = await Sandbox.list();
const cutoff = new Date(Date.now() - 60 * 60 * 1000); // 1 hour ago

for (const sandbox of sandboxes) {
  const info = await sandbox.getInfo();
  const created = new Date(info.createdAt);
  
  if (created < cutoff) {
    console.log(`Cleaning up old sandbox: ${sandbox.sandboxId}`);
    await 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

SDK: Sandbox.list() - Python SDK method
CLI - Command-line interface
SDK: Sandbox.iter() - Python SDK iterator method
API: GET /v1/sandboxes - Control Plane API endpoint

Creating Sandboxes - Create new sandboxes
Connecting to Sandboxes - Connect to existing sandboxes
Managing Sandbox State - Control sandbox lifecycle
API Pagination - Understand pagination in list results

Next Steps

Learn about Connecting to Existing sandboxes from the list
Understand Managing State operations
Explore Timeout Management for listed sandboxes

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Prerequisites

Basic Listing

Filtering by Status

Combining Filters

Lazy Iteration (Python)

Getting Detailed Information

Common Use Cases

Find a Specific Sandbox

Count Sandboxes by Status

Clean Up Old Sandboxes

API Direct Access

Implementation

Next Steps

​Prerequisites

​Basic Listing

​Filtering by Status

​Combining Filters

​Lazy Iteration (Python)

​Getting Detailed Information

​Common Use Cases

​Find a Specific Sandbox

​Count Sandboxes by Status

​Clean Up Old Sandboxes

​API Direct Access

​Implementation

​Related

​Next Steps

Prerequisites

Basic Listing

Filtering by Status

Combining Filters

Lazy Iteration (Python)

Getting Detailed Information

Common Use Cases

Find a Specific Sandbox

Count Sandboxes by Status

Clean Up Old Sandboxes

API Direct Access

Implementation

Related

Next Steps