Skip to main content
Execute shell commands in HopX sandboxes using the cmd command. Run commands synchronously or in the background with full control over execution environment.

​
Command Syntax

hopx cmd <subcommand> [options]

​
Subcommands

​
run

Run a shell command synchronously. Syntax: 
hopx cmd run SANDBOX_ID COMMAND [OPTIONS]
Arguments:
  • SANDBOX_ID - Sandbox ID (required)
  • COMMAND - Shell command to execute (required)
Options:
  • --timeout INTEGER - Command timeout in seconds
  • --workdir TEXT - Working directory for command execution
  • --env TEXT - Environment variable in KEY=VALUE format (repeatable)
  • --background - Run command in background (returns immediately)
  • --output, -o FORMAT - Output format: table, json, plain (default: table)
Examples: 
# Run simple command
hopx cmd run sb_abc123 "ls -la"

# Run with timeout
hopx cmd run sb_abc123 "npm install" --timeout 300

# Run in working directory
hopx cmd run sb_abc123 "pwd" --workdir /app

# Run with environment variables
hopx cmd run sb_abc123 "echo $API_KEY" --env API_KEY=secret123

# Run in background
hopx cmd run sb_abc123 "python server.py" --background

# Get JSON output
hopx cmd run sb_abc123 "ls -la" --output json
Expected Output: 
total 16
drwxr-xr-x 2 user user 4096 Jan 27 10:00 .
drwxr-xr-x 3 user user 4096 Jan 27 10:00 ..
-rw-r--r-- 1 user user   13 Jan 27 10:00 data.txt
Expected Output (JSON): 
{
  "stdout": "total 16\ndrwxr-xr-x 2 user user 4096 Jan 27 10:00 .\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.5
}
Exit Codes:
  • 0 - Success
  • 1 - Command execution error
  • 3 - Authentication error
  • 4 - Sandbox not found
  • 5 - Timeout

​
exec

Execute a shell command (alias for run). Syntax: 
hopx cmd exec SANDBOX_ID COMMAND [OPTIONS]
Same as run command. See run for options and examples.

​
Shell Scripting Examples

​
Install Dependencies

#!/bin/bash
set -e

SANDBOX_ID="sb_abc123"

# Install packages
hopx cmd run "$SANDBOX_ID" "pip install requests pandas" --timeout 120

# Verify installation
hopx cmd run "$SANDBOX_ID" "pip list | grep requests"

​
Run Tests

#!/bin/bash

# Run tests with environment variables
hopx cmd run sb_abc123 "npm test" \
  --env NODE_ENV=test \
  --env CI=true \
  --workdir /app

​
Background Process

#!/bin/bash

# Start server in background
hopx cmd run sb_abc123 "python server.py" --background

# Server is now running in background
# Use other commands to interact with it

​
Chain Commands

#!/bin/bash

# Chain multiple commands
hopx cmd run sb_abc123 "cd /app && npm install && npm test"

​
Next Steps