Skip to main content
Execute shell commands, install packages, and run system utilities in your sandbox. 
curl -X POST https://api.gravixlayer.com/v1/agents/sandboxes/{sandbox_id}/commands/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls",
    "args": ["-la", "/home/user"],
    "timeout": 10000
  }'

​
Request Parameters

ParameterTypeRequiredDescription
commandstringYesCommand to execute
argsarrayNoCommand arguments
timeoutintegerNoTimeout in milliseconds (default: 30000)

​
Response

{
  "stdout": "total 16\ndrwxr-xr-x 2 user user 4096 Jan 27 10:35 .\ndrwxr-xr-x 3 root root 4096 Jan 27 10:30 ..\n-rw-r--r-- 1 user user   95 Jan 27 10:35 config.json",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 45,
  "success": true
}

​
Common Commands

​
Install Python Packages

curl -X POST https://api.gravixlayer.com/v1/agents/sandboxes/{sandbox_id}/commands/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "pip",
    "args": ["install", "streamlit", "plotly"],
    "timeout": 120000
  }'

​
Install Node.js Packages

curl -X POST https://api.gravixlayer.com/v1/agents/sandboxes/{sandbox_id}/commands/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm",
    "args": ["install", "puppeteer", "sharp"],
    "timeout": 180000
  }'

​
System Information

curl -X POST https://api.gravixlayer.com/v1/agents/sandboxes/{sandbox_id}/commands/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "uname",
    "args": ["-a"],
    "timeout": 5000
  }'

​
Error Handling

Command Not Found (exit code 127): 
{
  "stdout": "",
  "stderr": "bash: nonexistent: command not found",
  "exit_code": 127,
  "duration_ms": 12,
  "success": false
}

​
Next Steps

Run Python Code

Execute Python code with installed packages

Run JavaScript Code

Execute Node.js code with installed packages

Read Files

Read files created by commands

Templates

Learn about pre-installed packages