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 background and return immediately with a process ID. Perfect for long-running commands like servers, monitoring, or batch jobs.

​
Endpoint

POST /commands/background

​
Request

​
Headers

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

​
Body Parameters

ParameterTypeRequiredDescription
commandstringYesShell command to execute
timeoutintegerNoMax execution time in seconds (default: 300)
working_dirstringNoWorking directory
envobjectNoEnvironment variables
namestringNoProcess name for identification

​
Example Request

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python -m http.server 8000",
    "working_dir": "/workspace",
    "name": "web-server"
  }'

​
Response

​
Success (200 OK)

{
  "process_id": "proc_abc123",
  "execution_id": "exec_xyz789",
  "status": "running"
}

​
Response Fields

FieldTypeDescription
process_idstringProcess ID (use to check status or kill)
execution_idstringExecution ID
statusstringInitial status (queued or running)

​
Status Codes

CodeDescription
200Command started
400Invalid request
401Unauthorized
500Failed to start command

​
Use Cases

​
Start Web Server

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python -m http.server 8080",
    "working_dir": "/workspace",
    "env": {
      "PORT": "8080"
    },
    "name": "http-server"
  }'

​
Run Long Processing Job

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "for i in {1..3600}; do echo \"Processing batch $i\"; sleep 1; done > /workspace/log.txt",
    "timeout": 7200,
    "name": "batch-processing"
  }'

​
Monitor Files

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "tail -f /workspace/application.log",
    "name": "log-monitor"
  }'

​
Start Development Server

curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm run dev",
    "working_dir": "/workspace/myapp",
    "env": {
      "NODE_ENV": "development",
      "PORT": "3000"
    },
    "name": "dev-server"
  }'

​
Check Process Status

Use the List Processes endpoint: 
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq '.processes[] | select(.process_id == "proc_abc123")'

​
Kill Background Command

Use the Kill Process endpoint: 
curl -X DELETE https://sandbox_abc123xyz.hopx.dev/execute/kill \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "proc_abc123"
  }'

​
Next Steps