Run Command

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

Parameter	Type	Required	Description
`command`	string	Yes	Shell command to execute
`timeout`	integer	No	Command timeout in seconds (default: 30)
`working_dir`	string	No	Working directory (default: `/workspace`)
`env`	object	No	Environment 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

Field	Type	Description
`stdout`	string	Standard output
`stderr`	string	Standard error
`exit_code`	integer	Exit code (0 = success)

Status Codes

Code	Description
200	Command completed
400	Invalid request (missing command)
401	Unauthorized
408	Command timeout
500	Command 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"
  }'

SDK: sandbox.commands.run() - Python SDK method
CLI Commands - Shell commands from CLI

Next Steps

Run Command in Background - Run long-running commands
Execute Code - Execute code directly
File Operations - Read and write files

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Errors

Command Failed (500)

Use Cases

Install Packages

Check System Information

File Operations

Git Operations

Build and Test

Pipeline Multiple Commands

Next Steps

​Endpoint

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (200 OK)

​Response Fields

​Status Codes

​Errors

​Command Failed (500)

​Use Cases

​Install Packages

​Check System Information

​File Operations

​Git Operations

​Build and Test

​Pipeline Multiple Commands

​Related

​Next Steps

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Errors

Command Failed (500)

Use Cases

Install Packages

Check System Information

File Operations

Git Operations

Build and Test

Pipeline Multiple Commands

Related

Next Steps