Skip to main content
The Hopx Python SDK provides powerful code execution capabilities with support for multiple programming languages, rich output capture, and streaming execution.

​
Basic Execution

​
run_code()

Execute code synchronously and wait for results. 
result = sandbox.run_code('print("Hello, World!")')
print(result.stdout)
print(result.stderr)
print(f"Exit code: {result.exit_code}")
print(f"Execution time: {result.execution_time}s")
Method Signature: 
def run_code(
    self,
    code: str,
    *,
    language: str = "python",
    timeout: int = 60,
    working_dir: str = "/workspace",
    env: Optional[Dict[str, str]] = None,
    rich: bool = False,
) -> ExecutionResult
Parameters:
  • code (str): Code to execute
  • language (str): Programming language - "python", "javascript", "bash", or "go" (default: "python")
  • timeout (int): Execution timeout in seconds (default: 60)
  • working_dir (str): Working directory for execution (default: "/workspace")
  • env (Dict[str, str], optional): Environment variables for this execution only
  • rich (bool): If True, captures rich outputs like plots and DataFrames (default: False)
Returns: ExecutionResult object

​
ExecutionResult

The ExecutionResult object contains execution results and metadata: 
@dataclass
class ExecutionResult:
    stdout: str              # Standard output
    stderr: str              # Standard error
    exit_code: int           # Exit code (0 = success)
    execution_time: float    # Execution time in seconds
    rich_outputs: List[RichOutput]  # Rich outputs (plots, DataFrames)
    
    # Convenience properties
    @property
    def success(self) -> bool:
        """True if exit_code == 0"""
        return self.exit_code == 0
    
    @property
    def rich_count(self) -> int:
        """Number of rich outputs captured"""
        return len(self.rich_outputs)
Example: 
result = sandbox.run_code('print("Hello")')
if result.success:
    print("Execution succeeded!")
    print(f"Output: {result.stdout}")
else:
    print(f"Execution failed: {result.stderr}")
    print(f"Exit code: {result.exit_code}")

​
Supported Languages

​
Python

result = sandbox.run_code(
    '''
import pandas as pd
df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
print(df)
''',
    language="python"
)

​
JavaScript (Node.js)

result = sandbox.run_code(
    '''
const fs = require('fs');
const data = fs.readFileSync('/workspace/data.txt', 'utf8');
console.log(data);
''',
    language="javascript"
)

​
Bash

result = sandbox.run_code(
    '''
#!/bin/bash
echo "Hello from Bash!"
ls -la /workspace
''',
    language="bash"
)

​
Go

result = sandbox.run_code(
    '''
package main
import "fmt"
func main() {
    fmt.Println("Hello from Go!")
}
''',
    language="go"
)

​
Rich Outputs

Enable rich output capture to automatically capture plots, DataFrames, and other visual outputs: 
result = sandbox.run_code(
    '''
import matplotlib.pyplot as plt
import pandas as pd

# Create DataFrame
df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
print(df)

# Create plot
plt.plot([1, 2, 3], [4, 5, 6])
plt.savefig('/workspace/plot.png')
''',
    rich=True  # Enable rich output capture
)

# Access rich outputs
print(f"Captured {result.rich_count} rich outputs")
for output in result.rich_outputs:
    print(f"Type: {output.type}")
    print(f"Path: {output.path}")
    if output.type == "image":
        # Download image
        img_data = sandbox.files.read_bytes(output.path)
        with open('plot.png', 'wb') as f:
            f.write(img_data)
Rich Output Types:
  • "image": Images (PNG, JPG, etc.) from matplotlib, plotly, etc.
  • "dataframe": Pandas DataFrames (automatically formatted)
  • "text": Other rich text outputs

​
Environment Variables

Pass environment variables for a specific execution: 
result = sandbox.run_code(
    'import os; print(os.environ.get("API_KEY"))',
    env={
        "API_KEY": "sk-test-123",
        "DEBUG": "true"
    }
)
Environment Variable Priority:
  1. Execution-specific env vars (from env parameter)
  2. Global sandbox env vars (from sandbox.env)
  3. Agent default env vars

​
Working Directory

Specify a custom working directory: 
# Create directory
sandbox.files.mkdir('/workspace/project')

# Execute code in that directory
result = sandbox.run_code(
    'print(os.getcwd())',
    working_dir='/workspace/project'
)
# Output: /workspace/project

​
Timeouts

Set custom timeouts for long-running code: 
# Long-running computation
result = sandbox.run_code(
    '''
import time
for i in range(100):
    print(f"Step {i}")
    time.sleep(0.1)
''',
    timeout=300  # 5 minutes
)
Note: The timeout includes both execution time and network overhead. For very long operations, consider using async execution.

​
Error Handling

Handle execution errors gracefully: 
from hopx_ai.errors import CodeExecutionError

try:
    result = sandbox.run_code('invalid python syntax here')
except CodeExecutionError as e:
    print(f"Code execution failed: {e.message}")
    print(f"Language: {e.language}")
    print(f"Request ID: {e.request_id}")
except Exception as e:
    print(f"Unexpected error: {e}")
Common Error Scenarios:
  • Syntax Errors: Invalid code syntax
  • Runtime Errors: Code execution failures
  • Timeout Errors: Execution exceeds timeout
  • Resource Errors: Insufficient resources

​
IPython Integration

For interactive Python sessions, use IPython: 
# Note: IPython execution is available via the agent API
# This requires direct agent client usage
result = sandbox.run_code(
    '''
# IPython magic commands work
%matplotlib inline
import matplotlib.pyplot as plt
plt.plot([1, 2, 3])
''',
    # IPython mode is typically handled by the agent
)

​
Best Practices

​
1. Check Execution Results

Always check result.success or result.exit_code: 
result = sandbox.run_code('some_code_here')
if not result.success:
    print(f"Error: {result.stderr}")
    return

​
2. Use Rich Outputs for Visualizations

Enable rich outputs when creating plots or DataFrames: 
result = sandbox.run_code(
    '''
import matplotlib.pyplot as plt
plt.plot([1, 2, 3])
plt.savefig('/workspace/plot.png')
''',
    rich=True
)

​
3. Set Appropriate Timeouts

Use longer timeouts for operations that may take time: 
# Quick operations
result = sandbox.run_code('print("Hello")', timeout=10)

# Long operations
result = sandbox.run_code('train_model()', timeout=1800)  # 30 minutes

​
4. Use Environment Variables for Secrets

Pass sensitive data via environment variables: 
result = sandbox.run_code(
    'import os; api_key = os.environ.get("API_KEY")',
    env={"API_KEY": "sk-secret-key"}
)

​
5. Handle Large Outputs

For large outputs, consider writing to files instead: 
# Instead of printing large data
sandbox.run_code('''
import pandas as pd
df = pd.read_csv('large_file.csv')
df.to_csv('/workspace/result.csv', index=False)
''')

# Then download the file
sandbox.files.download('/workspace/result.csv', './result.csv')

​
Examples

​
Data Analysis

result = sandbox.run_code(
    '''
import pandas as pd
import numpy as np

# Load data
df = pd.DataFrame({
    "x": np.random.randn(100),
    "y": np.random.randn(100)
})

# Analyze
print(f"Mean x: {df['x'].mean()}")
print(f"Mean y: {df['y'].mean()}")
print(f"Correlation: {df['x'].corr(df['y'])}")
''',
    rich=True
)

​
Machine Learning

result = sandbox.run_code(
    '''
from sklearn.linear_model import LinearRegression
import numpy as np

X = np.array([[1], [2], [3], [4]])
y = np.array([2, 4, 6, 8])

model = LinearRegression()
model.fit(X, y)

print(f"Score: {model.score(X, y)}")
print(f"Predictions: {model.predict([[5], [6]])}")
''',
    timeout=120
)

​
Web Scraping

result = sandbox.run_code(
    '''
import requests
from bs4 import BeautifulSoup

response = requests.get('https://example.com')
soup = BeautifulSoup(response.text, 'html.parser')
print(soup.title.string)
''',
    env={"USER_AGENT": "MyBot/1.0"}
)