Skip to main content
Control the lifecycle of your sandboxes by starting, stopping, pausing, and resuming them. This allows you to manage resources efficiently and maintain state across sessions.

​
Prerequisites

Before you begin, make sure you have:
  • Existing sandbox - A sandbox that was created (see Creating Sandboxes)
  • Sandbox object - A Sandbox instance connected to your sandbox
  • Basic understanding - Familiarity with sandbox states and lifecycle

​
Sandbox States

Sandboxes can be in one of these states:
  • running - Active and ready to execute code
  • stopped - Shut down but can be restarted
  • paused - Temporarily suspended, can be resumed
  • creating - Currently being created
When you pause a sandbox, its state is preserved. When you resume it, everything continues from where it left off. Stopped sandboxes lose their runtime state but can be restarted.

​
Getting Current State

Check the current state of a sandbox:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

print(f"Status: {info.status}")
print(f"Sandbox ID: {info.sandbox_id}")
Expected Output:
Status: running
Sandbox ID: 1763309903rt5vs4lm

​
Starting a Sandbox

Start a stopped sandbox:
  • Python
  • JavaScript
from hopx_ai import Sandbox

# Connect to a stopped sandbox
sandbox = Sandbox.connect("sandbox_id")

# Check current status
info = sandbox.get_info()
print(f"Current status: {info.status}")  # "stopped"

# Start the sandbox
sandbox.start()

# Verify it's running
info = sandbox.get_info()
print(f"New status: {info.status}")  # "running"
Expected Output:
Current status: stopped
New status: running

​
Stopping a Sandbox

Stop a running sandbox (preserves filesystem but loses runtime state):
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Stop the sandbox
sandbox.stop()

# Verify it's stopped
info = sandbox.get_info()
print(f"Status: {info.status}")  # "stopped"

# Can start it again later
sandbox.start()
Expected Output:
Status: stopped

​
Pausing a Sandbox

Pause a running sandbox (preserves full state including memory):
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Set some state
sandbox.run_code('x = 42', language="python")

# Pause the sandbox
sandbox.pause()

# Verify it's paused
info = sandbox.get_info()
print(f"Status: {info.status}")  # "paused"
Expected Output:
Status: paused

​
Resuming a Sandbox

Resume a paused sandbox (restores full state):
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandbox = Sandbox.connect("sandbox_id")  # Automatically resumes if paused

# Or manually resume
sandbox.resume()

# Verify it's running
info = sandbox.get_info()
print(f"Status: {info.status}")  # "running"

# State is preserved
result = sandbox.run_code('print(x)', language="python")
print(result.stdout)  # "42" - state preserved!
Expected Output:
Status: running
42

​
Complete State Management Example

Here’s a complete example showing all state operations:
  • Python
  • JavaScript
from hopx_ai import Sandbox

# Create sandbox
sandbox = Sandbox.create(template="code-interpreter")
print(f"Created: {sandbox.get_info().status}")  # "running"

# Set some state
sandbox.run_code('data = [1, 2, 3, 4, 5]', language="python")

# Pause
sandbox.pause()
print(f"After pause: {sandbox.get_info().status}")  # "paused"

# Resume (state preserved)
sandbox.resume()
print(f"After resume: {sandbox.get_info().status}")  # "running"

# Verify state preserved
result = sandbox.run_code('print(sum(data))', language="python")
print(f"Sum: {result.stdout}")  # "15" - state preserved!

# Stop
sandbox.stop()
print(f"After stop: {sandbox.get_info().status}")  # "stopped"

# Start again (state lost)
sandbox.start()
result = sandbox.run_code('print(data)', language="python")
print(f"Data: {result.stderr}")  # Error - state lost on stop

​
State Transitions

Understanding state transitions helps you manage sandboxes effectively: 
creating → running → paused → running
                ↓         ↓
             stopped → running
                ↓
            (deleted)

Pause vs Stop

Pause: Preserves full state (memory, variables, running processes). Fast resume. Stop: Preserves filesystem only. Runtime state is lost. Requires full restart.

When to Use

Pause: When you need to temporarily suspend work but keep everything in memory. Stop: When you want to free resources but keep files for later.

​
Error Handling

Handle state transition errors:
  • Python
  • JavaScript
from hopx_ai import Sandbox
from hopx_ai.errors import APIError

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

try:
    # Try to pause
    sandbox.pause()
except APIError as e:
    print(f"Failed to pause: {e}")

try:
    # Try to start (might already be running)
    sandbox.start()
except APIError as e:
    print(f"Failed to start: {e}")

​
Best Practices

1

1. Use Pause for Temporary Suspension

Use pause() when you need to temporarily suspend work but want to preserve all state. Resume is fast and preserves everything.
2

2. Use Stop for Resource Management

Use stop() when you want to free resources but keep the filesystem. Files are preserved, but runtime state is lost.
3

3. Check Status Before Operations

Always check the sandbox status before performing operations to avoid errors.
4

4. Handle State Transitions Gracefully

Handle errors when transitioning states - a sandbox might already be in the desired state.
5

5. Clean Up When Done

Always call kill() when you’re completely done with a sandbox to free resources.

​
Implementation

​
Next Steps