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 the sandbox and wait for completion. Commands run in /bin/sh -c and return stdout, stderr, and exit code.

​
Endpoint

POST /commands/run

​
Request

​
Headers

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

​
Body Parameters

ParameterTypeRequiredDescription
commandstringYesShell command to execute
timeoutintegerNoCommand timeout in seconds (default: 30)
working_dirstringNoWorking directory (default: /workspace)
envobjectNoEnvironment variables for this command only

​
Example Request

Run a simple command: 
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la /workspace"
  }'
Run with custom environment: 
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "echo $MY_VAR",
    "env": {
      "MY_VAR": "hello"
    }
  }'

​
Response

​
Success (200 OK)

{
  "stdout": "total 8\ndrwxr-xr-x 2 user user 4096 Jan 28 00:00 .\ndrwxr-xr-x 3 user user 4096 Jan 28 00:00 ..\n",
  "stderr": "",
  "exit_code": 0
}

​
Response Fields

FieldTypeDescription
stdoutstringStandard output
stderrstringStandard error
exit_codeintegerExit code (0 = success)

​
Status Codes

CodeDescription
200Command completed
400Invalid request (missing command)
401Unauthorized
408Command timeout
500Command failed

​
Errors

​
Command Failed (500)

{
  "stdout": "",
  "stderr": "ls: cannot access '/nonexistent': No such file or directory\n",
  "exit_code": 2
}
Cause: Command execution failed. Fix: Check the stderr field for error details and verify the command.

​
Use Cases

​
Install Packages

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "pip install requests numpy",
    "timeout": 120
  }'

​
Check System Information

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "uname -a && df -h && free -h"
  }'

​
File Operations

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "cat /workspace/data.txt | wc -l",
    "working_dir": "/workspace"
  }'

​
Git Operations

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git clone https://github.com/user/repo.git && cd repo && git log -1",
    "working_dir": "/workspace",
    "timeout": 60
  }'

​
Build and Test

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm install && npm test",
    "working_dir": "/workspace/project",
    "timeout": 300
  }'

​
Pipeline Multiple Commands

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "mkdir -p /workspace/output && python process.py && mv result.csv /workspace/output/",
    "working_dir": "/workspace"
  }'

​
Next Steps