Timeout

Sandboxes can be configured with automatic timeout values that determine when they are automatically destroyed. This helps manage resources and costs while ensuring sandboxes don’t run indefinitely.

Overview

Timeout management allows you to:

Set an initial timeout when creating a sandbox
Extend the timeout for running sandboxes
Automatically destroy sandboxes after the timeout expires

When a timeout expires, the sandbox is automatically destroyed. All data in the sandbox is lost. Make sure to save important data before the timeout expires.

Setting Timeout on Creation

Set a timeout when creating a sandbox:

Python
JavaScript

from hopx_ai import Sandbox

# Create sandbox with 1 hour timeout
sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=3600  # 1 hour in seconds
)

info = sandbox.get_info()
if info.expires_at:
    print(f"Sandbox expires at: {info.expires_at}")

Expected Output:

Sandbox expires at: 2025-01-27T11:00:00Z

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

// Create sandbox with 1 hour timeout
const sandbox = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 3600  // 1 hour in seconds
});

const info = await sandbox.getInfo();
if (info.expiresAt) {
  console.log(`Sandbox expires at: ${info.expiresAt}`);
}

Expected Output:

Sandbox expires at: 2025-01-27T11:00:00Z

Extending Timeout

Extend the timeout for an existing sandbox:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Extend timeout to 2 hours from now
sandbox.set_timeout(7200)  # 2 hours in seconds

# Verify new timeout
info = sandbox.get_info()
if info.expires_at:
    print(f"New expiration: {info.expires_at}")

Expected Output:

New expiration: 2025-01-27T12:00:00Z

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

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Extend timeout to 2 hours from now
await sandbox.setTimeout(7200);  // 2 hours in seconds

// Verify new timeout
const info = await sandbox.getInfo();
if (info.expiresAt) {
  console.log(`New expiration: ${info.expiresAt}`);
}

Expected Output:

New expiration: 2025-01-27T12:00:00Z

The set_timeout() method sets a new timeout duration from the current time, not from the original expiration. Each call resets the timer.

Common Timeout Values

Use these common timeout values:

Python
JavaScript

from hopx_ai import Sandbox

# Quick tasks (5 minutes)
sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=300
)

# Standard tasks (30 minutes)
sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=1800
)

# Long-running tasks (1 hour)
sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=3600
)

# Extended tasks (4 hours)
sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=14400
)

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

// Quick tasks (5 minutes)
const sandbox1 = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 300
});

// Standard tasks (30 minutes)
const sandbox2 = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 1800
});

// Long-running tasks (1 hour)
const sandbox3 = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 3600
});

// Extended tasks (4 hours)
const sandbox4 = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 14400
});

Checking Expiration

Check when a sandbox will expire:

Python
JavaScript

from hopx_ai import Sandbox
from datetime import datetime

sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=3600
)

info = sandbox.get_info()
if info.expires_at:
    expires = datetime.fromisoformat(info.expires_at.replace('Z', '+00:00'))
    now = datetime.now(expires.tzinfo)
    remaining = expires - now
    
    print(f"Expires at: {info.expires_at}")
    print(f"Time remaining: {remaining.total_seconds() / 60:.1f} minutes")

Expected Output:

Expires at: 2025-01-27T11:00:00Z
Time remaining: 55.2 minutes

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

const sandbox = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 3600
});

const info = await sandbox.getInfo();
if (info.expiresAt) {
  const expires = new Date(info.expiresAt);
  const now = new Date();
  const remaining = (expires - now) / 1000 / 60;  // minutes
  
  console.log(`Expires at: ${info.expiresAt}`);
  console.log(`Time remaining: ${remaining.toFixed(1)} minutes`);
}

Expected Output:

Expires at: 2025-01-27T11:00:00Z
Time remaining: 55.2 minutes

Extending Before Expiration

Extend timeout before it expires to prevent automatic destruction:

Python
JavaScript

from hopx_ai import Sandbox
from datetime import datetime

sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=3600
)

# Check remaining time
info = sandbox.get_info()
if info.expires_at:
    expires = datetime.fromisoformat(info.expires_at.replace('Z', '+00:00'))
    now = datetime.now(expires.tzinfo)
    remaining_minutes = (expires - now).total_seconds() / 60
    
    # Extend if less than 10 minutes remaining
    if remaining_minutes < 10:
        print("Extending timeout...")
        sandbox.set_timeout(3600)  # Extend by 1 hour
        print("Timeout extended")

Expected Output:

Extending timeout...
Timeout extended

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

const sandbox = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 3600
});

// Check remaining time
let info = await sandbox.getInfo();
if (info.expiresAt) {
  const expires = new Date(info.expiresAt);
  const now = new Date();
  const remainingMinutes = (expires - now) / 1000 / 60;
  
  // Extend if less than 10 minutes remaining
  if (remainingMinutes < 10) {
    console.log('Extending timeout...');
    await sandbox.setTimeout(3600);  // Extend by 1 hour
    console.log('Timeout extended');
  }
}

Expected Output:

Extending timeout...
Timeout extended

No Timeout (Indefinite)

Create a sandbox without a timeout (runs until manually killed):

Python
JavaScript

from hopx_ai import Sandbox

# Create without timeout (or set to None)
sandbox = Sandbox.create(
    template="code-interpreter"
    # timeout_seconds not specified = no timeout
)

info = sandbox.get_info()
if info.expires_at:
    print(f"Expires: {info.expires_at}")
else:
    print("No timeout - runs indefinitely")

Expected Output:

No timeout - runs indefinitely

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

// Create without timeout
const sandbox = await Sandbox.create({
  template: 'code-interpreter'
  // timeoutSeconds not specified = no timeout
});

const info = await sandbox.getInfo();
if (info.expiresAt) {
  console.log(`Expires: ${info.expiresAt}`);
} else {
  console.log('No timeout - runs indefinitely');
}

Expected Output:

No timeout - runs indefinitely

Complete Example

Here’s a complete example showing timeout management:

Python
JavaScript

from hopx_ai import Sandbox
from datetime import datetime

# Create with initial timeout
sandbox = Sandbox.create(
    template="code-interpreter",
    timeout_seconds=1800  # 30 minutes
)

info = sandbox.get_info()
print(f"Initial timeout: {info.expires_at}")

# Do some work
sandbox.run_code('print("Working...")', language="python")

# Extend timeout before expiration
sandbox.set_timeout(3600)  # Extend to 1 hour from now

info = sandbox.get_info()
print(f"Extended timeout: {info.expires_at}")

# Check remaining time
if info.expires_at:
    expires = datetime.fromisoformat(info.expires_at.replace('Z', '+00:00'))
    remaining = (expires - datetime.now(expires.tzinfo)).total_seconds()
    print(f"Time remaining: {remaining / 60:.1f} minutes")

Expected Output:

Initial timeout: 2025-01-27T10:30:00Z
Working...
Extended timeout: 2025-01-27T11:30:00Z
Time remaining: 60.0 minutes

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

// Create with initial timeout
const sandbox = await Sandbox.create({
  template: 'code-interpreter',
  timeoutSeconds: 1800  // 30 minutes
});

let info = await sandbox.getInfo();
console.log(`Initial timeout: ${info.expiresAt}`);

// Do some work
await sandbox.runCode('print("Working...")', { language: 'python' });

// Extend timeout before expiration
await sandbox.setTimeout(3600);  // Extend to 1 hour from now

info = await sandbox.getInfo();
console.log(`Extended timeout: ${info.expiresAt}`);

// Check remaining time
if (info.expiresAt) {
  const expires = new Date(info.expiresAt);
  const remaining = (expires - new Date()) / 1000 / 60;
  console.log(`Time remaining: ${remaining.toFixed(1)} minutes`);
}

Expected Output:

Initial timeout: 2025-01-27T10:30:00Z
Working...
Extended timeout: 2025-01-27T11:30:00Z
Time remaining: 60.0 minutes

API Direct Access

You can also manage timeouts using direct API calls:

# Set timeout when creating
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer your-API key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "timeout_seconds": 3600
  }'

# Update timeout for existing sandbox
curl -X PUT https://api.hopx.dev/v1/sandboxes/{sandbox_id}/timeout \
  -H "Authorization: Bearer your-API key" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 7200
  }'

Best Practices

1. Set Appropriate Initial Timeouts

Set timeouts based on expected task duration. For quick scripts, use shorter timeouts. For long-running tasks, set longer timeouts.

2. Monitor Remaining Time

Check expiration time regularly for long-running sandboxes to avoid unexpected destruction.

3. Extend Before Expiration

Extend timeouts before they expire to prevent data loss. Consider setting up monitoring to alert when time is running low.

4. Save Important Data

Always save important data before timeout expires. Consider downloading files or storing results externally.

5. Use No Timeout for Development

For development and debugging, consider creating sandboxes without timeouts, but remember to clean them up manually.

Timeout vs Manual Cleanup

Automatic Timeout

Set timeout_seconds when creating or use set_timeout() to automatically destroy sandboxes after a specified duration. Best for production workloads.

Manual Cleanup

Call sandbox.kill() when done. Best for development or when you need precise control over when sandboxes are destroyed.

Implementation

SDK: sandbox.set_timeout() - Python SDK method
CLI - Command-line interface
API: PUT /v1/sandboxes/:id/timeout - Control Plane API endpoint

Creating Sandboxes - Set timeout on creation
Managing Sandbox State - Control sandbox lifecycle
Connecting to Sandboxes - Connect to existing sandboxes

Next Steps

Learn about Creating Sandboxes with timeout configuration
Explore Managing State for lifecycle control
Review Listing Sandboxes to monitor sandbox status

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Setting Timeout on Creation

Extending Timeout

Common Timeout Values

Checking Expiration

Extending Before Expiration

No Timeout (Indefinite)

Complete Example

API Direct Access

Best Practices

Timeout vs Manual Cleanup

Automatic Timeout

Manual Cleanup

Implementation

Next Steps

​Overview

​Setting Timeout on Creation

​Extending Timeout

​Common Timeout Values

​Checking Expiration

​Extending Before Expiration

​No Timeout (Indefinite)

​Complete Example

​API Direct Access

​Best Practices

​Timeout vs Manual Cleanup

Automatic Timeout

Manual Cleanup

​Implementation

​Related

​Next Steps

Overview

Setting Timeout on Creation

Extending Timeout

Common Timeout Values

Checking Expiration

Extending Before Expiration

No Timeout (Indefinite)

Complete Example

API Direct Access

Best Practices

Timeout vs Manual Cleanup

Implementation

Related

Next Steps