This guide covers all code execution methods available in Hopx Sandboxes, including synchronous execution, async execution, streaming, IPython support, and multiple programming languages.
Basic Code Execution
The simplest way to execute code is using run_code():
Python
JavaScript/TypeScript
from hopx_ai import Sandbox
import os
API_KEY = os.getenv("HOPX_API_KEY")
with Sandbox.create(template="code-interpreter", api_key=API_KEY) as sandbox:
result = sandbox.run_code("""
import sys
print(f"Python version: {sys.version}")
print("Hello from sandbox!")
""")
print(f"Success: {result.success}")
print(f"Exit code: {result.exit_code}")
print(f"Execution time: {result.execution_time}s")
print(f"Output:\n{result.stdout}")
Environment Variables in Code
Pass environment variables securely to your code execution:
Python
JavaScript/TypeScript
result = sandbox.run_code(
"""
import os
# These come from env parameter, NOT hardcoded!
api_key = os.environ.get('API_KEY')
debug = os.environ.get('DEBUG')
print(f"API Key: {api_key}")
print(f"Debug mode: {debug}")
""",
env={
"API_KEY": "sk-test-secret-key-123",
"DEBUG": "true"
}
)
Never hardcode secrets in your code. Always use environment variables passed through the env parameter.
Multiple Programming Languages
Execute code in different programming languages:
Python
JavaScript/TypeScript
# Python
result_py = sandbox.run_code(
'print("Hello from Python!")',
language="python"
)
# JavaScript
result_js = sandbox.run_code(
'console.log("Hello from JavaScript!")',
language="javascript"
)
# Bash
result_bash = sandbox.run_code(
'echo "Hello from Bash!"',
language="bash"
)
# Go
result_go = sandbox.run_code(
'''
package main
import "fmt"
func main() {
fmt.Println("Hello from Go!")
}
''',
language="go"
)
Rich Outputs (Plots, DataFrames, Images)
Capture rich outputs like matplotlib plots and pandas DataFrames:
Python
JavaScript/TypeScript
result = sandbox.run_code("""
import matplotlib.pyplot as plt
import pandas as pd
import numpy as np
# Create a plot
plt.figure(figsize=(8, 6))
x = np.linspace(0, 10, 100)
plt.plot(x, np.sin(x), label='sin(x)')
plt.plot(x, np.cos(x), label='cos(x)')
plt.legend()
plt.title('Trigonometric Functions')
plt.savefig('/tmp/plot.png')
print("Plot saved!")
# Create a DataFrame
df = pd.DataFrame({
'Name': ['Alice', 'Bob', 'Charlie'],
'Age': [25, 30, 35],
'Score': [95, 87, 92]
})
print(df)
""", rich=True)
print(f"Output:\n{result.stdout}")
if result.rich_outputs:
print(f"Rich outputs found: {len(result.rich_outputs)}")
for i, output in enumerate(result.rich_outputs):
print(f" {i+1}. Type: {output.type}")
print(f" Data keys: {list(output.data.keys())}")
Use rich=True (Python) or { rich: true } (JavaScript) only when you need to capture plots, DataFrames, or other rich outputs. The default execution is faster for simple code.
Asynchronous Execution
Start code execution without waiting for completion:
Python
JavaScript/TypeScript
import asyncio
sandbox = Sandbox.create(template="code-interpreter", api_key=API_KEY)
try:
# Start async execution (returns execution_id)
execution_id = sandbox.run_code_async("""
import time
print("Starting long computation...")
time.sleep(3)
print("Computation complete!")
""")
print(f"Execution started: {execution_id}")
print("(Non-blocking - can do other work)")
# Do other work while code executes...
await asyncio.sleep(1)
print("...doing other work...")
# Results are available via webhook or polling
print(f"Execution ID for later retrieval: {execution_id}")
finally:
sandbox.kill()
Background Execution
Fire-and-forget code execution:
Python
JavaScript/TypeScript
# Start background execution
execution_id = sandbox.run_code_background("""
import time
with open('/workspace/background_task.txt', 'w') as f:
for i in range(5):
f.write(f"Step {i+1}\n")
f.flush()
time.sleep(1)
f.write("Done!\n")
""")
print(f"Background execution started: {execution_id}")
print("(Running in background)")
# Can continue with other work immediately
print("...continuing with other work...")
# Check if file is being created
import time
time.sleep(2)
if sandbox.files.exists("/workspace/background_task.txt"):
content = sandbox.files.read("/workspace/background_task.txt")
print(f"Background task progress:\n{content}")
IPython/Jupyter Execution
Use IPython for Jupyter-like execution with rich display:
Python
JavaScript/TypeScript
result = sandbox.run_ipython("""
import pandas as pd
import numpy as np
# Last expression is automatically displayed
df = pd.DataFrame({
'A': np.random.rand(5),
'B': np.random.rand(5)
})
df.describe() # This will be displayed
""")
print(f"Success: {result.success}")
print(f"Output:\n{result.stdout}")
if result.rich_outputs:
print(f"Rich outputs: {len(result.rich_outputs)}")
Streaming Execution (Real-time)
Stream code execution output in real-time via WebSocket:
Python
JavaScript/TypeScript
import asyncio
sandbox = Sandbox.create(template="code-interpreter", api_key=API_KEY)
try:
code = """
import time
for i in range(5):
print(f"Step {i+1}/5")
time.sleep(1)
print("Complete!")
"""
print("Streaming output (real-time):")
async for message in sandbox.run_code_stream(code):
if message['type'] == 'stdout':
print(f" 📤 {message['data']}", end='')
elif message['type'] == 'stderr':
print(f" ⚠️ {message['data']}", end='')
elif message['type'] == 'result':
print(f"\nExit code: {message['exit_code']}")
print(f"Execution time: {message.get('execution_time', 0)}s")
elif message['type'] == 'complete':
print("Streaming complete!")
finally:
sandbox.kill()
Timeouts and Error Handling
Handle timeouts and errors gracefully:
Python
JavaScript/TypeScript
# This will timeout
try:
result = sandbox.run_code(
"""
import time
time.sleep(100) # Sleep longer than timeout
""",
timeout=2 # 2 second timeout
)
except Exception as e:
print(f"Caught timeout: {e}")
# This will succeed
result = sandbox.run_code(
"""
import time
time.sleep(1)
print("Done!")
""",
timeout=5
)
print(f"Within timeout: {result.stdout.strip()}")
Custom Working Directory
Execute code in a specific directory:
Python
JavaScript/TypeScript
# Create a directory
sandbox.files.mkdir("/workspace/myproject")
# Execute code in that directory
result = sandbox.run_code(
"""
import os
print(f"Current dir: {os.getcwd()}")
# Create file in current dir
with open('data.txt', 'w') as f:
f.write('Hello!')
""",
working_dir="/workspace/myproject"
)
print(f"Output:\n{result.stdout}")
# Verify file was created in correct directory
assert sandbox.files.exists("/workspace/myproject/data.txt")
print("File created in correct directory!")
Next Steps
