Skip to main content
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

​
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
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
)

​
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

​
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

​
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

​
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

​
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

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

2. Monitor Remaining Time

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

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

4. Save Important Data

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

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

​
Next Steps