Managing State

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

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

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

console.log(`Status: ${info.status}`);
console.log(`Sandbox ID: ${info.sandboxId}`);

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

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

// Connect to a stopped sandbox
const sandbox = await Sandbox.connect('sandbox_id');

// Check current status
let info = await sandbox.getInfo();
console.log(`Current status: ${info.status}`);  // "stopped"

// Start the sandbox
await sandbox.start();

// Verify it's running
info = await sandbox.getInfo();
console.log(`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

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

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

// Stop the sandbox
await sandbox.stop();

// Verify it's stopped
let info = await sandbox.getInfo();
console.log(`Status: ${info.status}`);  // "stopped"

// Can start it again later
await 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

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

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

// Set some state
await sandbox.runCode('x = 42', { language: 'python' });

// Pause the sandbox
await sandbox.pause();

// Verify it's paused
const info = await sandbox.getInfo();
console.log(`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

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

const sandbox = await Sandbox.connect('sandbox_id');  // Automatically resumes if paused

// Or manually resume
await sandbox.resume();

// Verify it's running
const info = await sandbox.getInfo();
console.log(`Status: ${info.status}`);  // "running"

// State is preserved
const result = await sandbox.runCode('print(x)', { language: 'python' });
console.log(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

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

// Create sandbox
const sandbox = await Sandbox.create({ template: 'code-interpreter' });
let info = await sandbox.getInfo();
console.log(`Created: ${info.status}`);  // "running"

// Set some state
await sandbox.runCode('data = [1, 2, 3, 4, 5]', { language: 'python' });

// Pause
await sandbox.pause();
info = await sandbox.getInfo();
console.log(`After pause: ${info.status}`);  // "paused"

// Resume (state preserved)
await sandbox.resume();
info = await sandbox.getInfo();
console.log(`After resume: ${info.status}`);  // "running"

// Verify state preserved
let result = await sandbox.runCode('print(sum(data))', { language: 'python' });
console.log(`Sum: ${result.stdout}`);  // "15" - state preserved!

// Stop
await sandbox.stop();
info = await sandbox.getInfo();
console.log(`After stop: ${info.status}`);  // "stopped"

// Start again (state lost)
await sandbox.start();
result = await sandbox.runCode('print(data)', { language: 'python' });
console.log(`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}")

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

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

try {
  // Try to pause
  await sandbox.pause();
} catch (error) {
  if (error instanceof APIError) {
    console.error(`Failed to pause: ${error.message}`);
  }
}

try {
  // Try to start (might already be running)
  await sandbox.start();
} catch (error) {
  if (error instanceof APIError) {
    console.error(`Failed to start: ${error.message}`);
  }
}

Best Practices

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. 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. Check Status Before Operations

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

4. Handle State Transitions Gracefully

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

5. Clean Up When Done

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

Implementation

SDK: sandbox.start() - Python SDK method
CLI - Command-line interface
SDK: sandbox.stop() - Python SDK method
SDK: sandbox.pause() - Python SDK method
SDK: sandbox.resume() - Python SDK method
API: POST /v1/sandboxes/:id/start - Control Plane API endpoint
API: POST /v1/sandboxes/:id/stop - Control Plane API endpoint
API: POST /v1/sandboxes/:id/pause - Control Plane API endpoint
API: POST /v1/sandboxes/:id/resume - Control Plane API endpoint

Creating Sandboxes - Create new sandboxes
Connecting to Sandboxes - Connect to existing sandboxes
Timeout Management - Set sandbox timeouts

Next Steps

Learn about Timeout Management to control sandbox lifetime
Review Creating Sandboxes for creating new sandboxes
Explore Listing Sandboxes to find sandboxes by status

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Prerequisites

Sandbox States

Getting Current State

Starting a Sandbox

Stopping a Sandbox

Pausing a Sandbox

Resuming a Sandbox

Complete State Management Example

State Transitions

Pause vs Stop

When to Use

Error Handling

Best Practices

Implementation

Next Steps

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

​Prerequisites

​Sandbox States

​Getting Current State

​Starting a Sandbox

​Stopping a Sandbox

​Pausing a Sandbox

​Resuming a Sandbox

​Complete State Management Example

​State Transitions

Pause vs Stop

When to Use

​Error Handling

​Best Practices

​Implementation

​Related

​Next Steps

Prerequisites

Sandbox States

Getting Current State

Starting a Sandbox

Stopping a Sandbox

Pausing a Sandbox

Resuming a Sandbox

Complete State Management Example

State Transitions

Error Handling

Best Practices

Implementation

Related

Next Steps