Documentation Index
Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
