Skip to main content
Sandboxes go through different states during their lifetime. Understanding the lifecycle helps you manage resources efficiently and control costs.

​
Lifecycle States

​
States

StateDescriptionBillableCan Execute Code
CreatingVM is spinning up❌ No❌ No
RunningVM is active and ready✅ Yes✅ Yes
StoppedVM is stopped (disk persists)💾 Disk only❌ No
PausedVM is paused (RAM persists)💾 Disk + RAM❌ No
DeletedVM is destroyed❌ No❌ No
Cost optimization tip: Use pause() instead of keeping sandboxes running when not in use. Paused sandboxes preserve state but cost less than running sandboxes.

​
Lifecycle Methods

The SDK provides methods to transition between states:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Create (creating → running)
sandbox = Sandbox.create(template="code-interpreter")

# Stop (running → stopped)
sandbox.stop()

# Start (stopped → running)
sandbox.start()

# Pause (running → paused)
sandbox.pause()

# Resume (paused → running)
sandbox.resume()

# Delete (any state → deleted)
sandbox.kill()

​
State Transitions

​
Creating → Running

When you create a sandbox, it starts in the Creating state and automatically transitions to Running when ready (typically ~100ms).
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")
# Sandbox is now in "Running" state

​
Running ↔ Stopped

Use stop() to halt execution while preserving disk state. Use start() to resume:
  • Python
  • JavaScript/TypeScript
# Stop the sandbox (preserves disk)
sandbox.stop()

# Later, start it again
sandbox.start()

​
Running ↔ Paused

Use pause() to preserve both RAM and disk state. Use resume() to restore:
  • Python
  • JavaScript/TypeScript
# Pause the sandbox (preserves RAM + disk)
sandbox.pause()

# Later, resume it
sandbox.resume()

​
Any State → Deleted

Use kill() to permanently delete a sandbox from any state:
  • Python
  • JavaScript/TypeScript
# Delete the sandbox (from any state)
sandbox.kill()

​
Best Practices

  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# Automatically kills sandbox after timeout
sandbox = Sandbox.create(template="code-interpreter", timeout_seconds=600)
result = sandbox.run_code("print('Hello')")
# Sandbox is automatically killed after 600 seconds
If you need to preserve in-memory state, use pause() instead of stop():
  • Python
  • JavaScript/TypeScript
# ✅ Good: Preserves RAM + disk
sandbox.pause()

# Later...
sandbox.resume()  # Everything is exactly as you left it
Always check sandbox state before performing operations:
  • Python
  • JavaScript/TypeScript
info = sandbox.get_info()

if info.status == "running":
    result = sandbox.run_code("print('Hello')")
else:
    sandbox.start()  # Start if not running
    result = sandbox.run_code("print('Hello')")

​
Next Steps

Core Concepts

Back to Core Concepts overview

Templates

Learn about templates

Resources

Configure sandbox resources

Cost Optimization

Optimize costs with lifecycle management