Skip to main content
Get up and running with HopX; this guide walks you through creating your first sandbox, executing code, and cleaning up.

​
What You’ll Learn

In this quickstart, you’ll learn how to:
  • Install and set up the HopX SDK (Python or JavaScript) or CLI
  • Create your first sandbox from a pre-built template
  • Execute code in multiple languages (Python, JavaScript, Bash, Go)
  • Work with files in sandboxes (read, write, list)
  • Clean up sandboxes to free resources
  • Use context managers for automatic cleanup (Python)

​
Prerequisites

  • HopX API key (get one here if you don’t have it)
  • Python 3.8+ or Node.js 18+ or CLI installed
  • Basic experience with Python, JavaScript, or command line

​
Run your first sandbox

Choose your preferred method: Python SDK, JavaScript SDK, or CLI. This guide focuses on SDKs. For CLI, see the CLI Quickstart.
1

Install the SDK or CLI

Install the HopX SDK for your preferred language, or use the CLI:
  • Python
  • JavaScript
  • CLI
pip install hopx-ai
2

Create Your First Sandbox

Create a sandbox using a pre-built template. Templates provide pre-configured environments with common tools and packages.
  • Python
  • JavaScript
from hopx_ai import Sandbox
from hopx_ai.exceptions import APIError, ResourceLimitError

try:
    # Create a sandbox with the code-interpreter template
    sandbox = Sandbox.create(
        template="code-interpreter",
        api_key="your-api-key-here"  # Or set HOPX_API_KEY env var
    )

    print(f"Sandbox created: {sandbox.sandbox_id}")
    print(f"Status: {sandbox.get_info().status}")
except APIError as e:
    print(f"API error: {e}")
except ResourceLimitError as e:
    print(f"Resource limit exceeded: {e}")
Expected Output:
Sandbox created: sandbox_abc123xyz
Status: running
You can also use Sandbox.create() without specifying an API key if you set the HOPX_API_KEY environment variable.
3

Execute Code

Run code in your sandbox.
  • Python
  • JavaScript
# Execute Python code
result = sandbox.run_code('''
import math

# Calculate the area of a circle
radius = 5
area = math.pi * radius ** 2
print(f"Area of circle with radius {radius}: {area:.2f}")
''', language: 'python')

print(result.stdout)
# Output: Area of circle with radius 5: 78.54

# Check if execution was successful
if result.success:
    print("✅ Code executed successfully!")
else:
    print(f"❌ Error: {result.stderr}")
The run_code() method automatically captures rich outputs like matplotlib plots and pandas DataFrames. See Rich Output Capture for more details.
The sandbox will execute code written in any language as long as the template you use provides the necessary dependencies.

See the Getting Template Details page for information on available templates and their environments, alternatively create your own template with the Building Templates guide.
4

Work with Files

Upload, read, and write files in your sandbox:
  • Python
  • JavaScript
# Write a file
sandbox.files.write('/workspace/data.txt', 'Hello, HopX!')

# Read the file
content = sandbox.files.read('/workspace/data.txt')
print(content)  # Output: Hello, HopX!

# List files in a directory
files = sandbox.files.list('/workspace')
for file in files:
    print(f"- {file.name} ({file.size} bytes)")
Expected Output:
Hello, HopX!
- data.txt (12 bytes)
- script.py (245 bytes)
5

Clean Up

Always clean up your sandbox when you’re done to free resources:
  • Python
  • JavaScript
# Delete the sandbox
sandbox.kill()
print("Sandbox deleted")
Expected Output:
Sandbox deleted
Calling kill() permanently deletes the sandbox and all its data. Make sure you’ve saved any important files before cleaning up. See Downloading Files for more details.

​
Using Context Managers (Python)

Python SDK supports context managers for automatic cleanup: 
from hopx_ai import Sandbox

# Automatically cleans up when exiting the context
with Sandbox.create(template="code-interpreter") as sandbox:
    result = sandbox.run_code('print("Hello from HopX!")', language='python')
    print(result.stdout)
    # Sandbox is automatically deleted when exiting the block
Expected Output: 
Hello from HopX!

​
Complete Example

Here’s a complete example that brings it all together:
  • Python
  • JavaScript
from hopx_ai import Sandbox

# Setup your API key as an env var or inject it here as previously instructed.
# Create sandbox
sandbox = Sandbox.create(template="code-interpreter") 

try:
    # Execute code
    result = sandbox.run_code('''
import math

# Calculate the area of a circle
radius = 5
area = math.pi * radius ** 2
print(f"Area of circle with radius {radius}: {area:.2f}")
    ''', language='python')
    
    print("Output:")
    print(result.stdout)

    sandbox.run_code('mkdir /workspace/test')
    
    # Work with files
    sandbox.files.write('/workspace/test/result.json', result.stdout)
    print("\n✅ Result saved to file")

    # List files in a directory
    files = sandbox.files.list('/workspace/test')
    for file in files:
        print(f"- {file.name} ({file.size} bytes)")\

    # Read the file
    content = sandbox.files.read('/workspace/test/result.json')
    print(content)
    
finally:
    # Always clean up
    sandbox.kill()
    print("✅ Sandbox cleaned up")

​
Next Steps

Now that you’ve created your first sandbox, explore more:
For AI agent developers, check out the MCP Integration guide to enable AI assistants to execute code safely in sandboxes.