> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Execution

> Execute code in HopX sandboxes using the CLI run command. Run Python, JavaScript, Bash, and Go code with options for files, environment variables, timeouts, and sandbox selection.

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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Long-running code with timeout
hopx run "import time; time.sleep(60)" --timeout 120
```

### Execute from stdin

```bash theme={null}
# 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:

```bash theme={null}
hopx run "print('Hello')" --output json
```

**Expected Output:**

```json theme={null}
{
  "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

```bash theme={null}
#!/bin/bash

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

### Execute with Error Handling

```bash theme={null}
#!/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

```bash theme={null}
#!/bin/bash

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

## Related

* **[CLI Quickstart](/cli/quickstart)** - Get started with CLI
* **[Sandbox Commands](/cli/commands/sandbox)** - Manage sandboxes
* **[Python SDK: Code Execution](/sdk/python/code-execution)** - Python SDK code execution
* **[JavaScript SDK: Code Execution](/sdk/javascript/code-execution)** - JavaScript SDK code execution
* **[API: Execute Code](/api/vm-agent/execute)** - REST API endpoint

## Next Steps

* Learn about [Sandbox Management](/cli/commands/sandbox) to create and manage sandboxes
* Explore [File Operations](/cli/commands/files) to work with files
* Review [Environment Variables](/cli/commands/env) to configure execution environment