Skip to main content

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.

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