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:
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}")
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}`);
}
Found 3 sandboxes
sandbox_abc123xyz: running
sandbox_def456uvw: paused
sandbox_ghi789rst: running
Filtering by Status
Filter sandboxes by their current status:
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)}")
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}`);
Running sandboxes: 2
Paused sandboxes: 1
Combining Filters
Combine multiple filters:
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:
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.
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
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
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
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®ion=us-east&limit=10" \
-H "Authorization: Bearer your-API key"
Implementation
Next Steps
