Skip to main content
Execute code in HopX sandboxes using the run command. Supports Python, JavaScript, Bash, and Go with options for files, environment variables, and timeouts.

​
Command Syntax

hopx run [CODE|FILE] [OPTIONS]

​
Options

  • CODE - Code to execute as argument (use - to read from stdin)
  • --file, -f PATH - File containing code to execute
  • --sandbox, -s TEXT - Sandbox ID (creates temporary sandbox if omitted)
  • --template, -t TEXT - Template for temporary sandbox (default: code-interpreter)
  • --language, -l TEXT - Programming language: python, javascript, bash, go
  • --timeout INTEGER - Execution timeout in seconds
  • --env TEXT - Environment variable in KEY=VALUE format (repeatable)
  • --workdir TEXT - Working directory for execution
  • --output, -o FORMAT - Output format: table, json, plain (default: table)

​
Examples

​
Execute Python Code

# Simple Python code
hopx run "print('Hello, World!')"

# Python with imports
hopx run "import sys; print(sys.version)"

# Python with calculations
hopx run "result = 2 + 2; print(f'Result: {result}')"
Expected Output: 
Hello, World!

​
Execute JavaScript

# Simple JavaScript
hopx run "console.log('Hello, World!')" -l javascript

# JavaScript with Node.js APIs
hopx run "console.log(process.version)" -l javascript
Expected Output: 
Hello, World!

​
Execute Bash

# Simple Bash command
hopx run "echo 'Hello, World!'" -l bash

# Bash with system commands
hopx run "ls -la && pwd" -l bash
Expected Output: 
Hello, World!

​
Execute from File

# Create local file
echo "print('Hello from file!')" > script.py

# Execute from file
hopx run -f script.py

# Execute JavaScript from file
hopx run -f script.js -l javascript
Expected Output: 
Hello from file!

​
Execute with Environment Variables

# Single environment variable
hopx run "import os; print(os.environ['API_KEY'])" -e API_KEY=secret123

# Multiple environment variables
hopx run "import os; print(os.environ['API_KEY'], os.environ['DEBUG'])" \
  -e API_KEY=secret123 \
  -e DEBUG=true
Expected Output: 
secret123

​
Execute in Existing Sandbox

# Create sandbox first
SANDBOX_ID=$(hopx sandbox create --template python --output json | jq -r '.id')

# Execute in existing sandbox
hopx run "print('Hello')" --sandbox "$SANDBOX_ID"
Expected Output: 
Hello

​
Execute with Timeout

# Long-running code with timeout
hopx run "import time; time.sleep(60)" --timeout 120

​
Execute from stdin

# Pipe code from stdin
echo "print('Hello from stdin!')" | hopx run -

# Pipe file content
cat script.py | hopx run -
Expected Output: 
Hello from stdin!

​
JSON Output

Get JSON output for scripting: 
hopx run "print('Hello')" --output json
Expected Output: 
{
  "stdout": "Hello\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.5
}

​
Exit Codes

  • 0 - Success
  • 1 - General error
  • 3 - Authentication error
  • 4 - Sandbox not found
  • 5 - Timeout

​
Shell Scripting Examples

​
Execute and Capture Output

#!/bin/bash

# Execute and capture output
OUTPUT=$(hopx run "print('Hello')" --output plain)
echo "Output: $OUTPUT"

​
Execute with Error Handling

#!/bin/bash

# Execute with error handling
if hopx run "print('Hello')" > /dev/null 2>&1; then
    echo "Execution successful"
else
    case $? in
        3) echo "Authentication failed" ;;
        4) echo "Sandbox not found" ;;
        5) echo "Execution timed out" ;;
        *) echo "Execution failed" ;;
    esac
    exit 1
fi

​
Execute Multiple Scripts

#!/bin/bash

# Execute multiple scripts
for script in *.py; do
    echo "Running $script..."
    hopx run -f "$script"
done

​
Next Steps