Run Command in Background

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

Parameter	Type	Required	Description
`command`	string	Yes	Shell command to execute
`timeout`	integer	No	Max execution time in seconds (default: 300)
`working_dir`	string	No	Working directory
`env`	object	No	Environment variables
`name`	string	No	Process 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

Field	Type	Description
`process_id`	string	Process ID (use to check status or kill)
`execution_id`	string	Execution ID
`status`	string	Initial status (`queued` or `running`)

Status Codes

Code	Description
200	Command started
400	Invalid request
401	Unauthorized
500	Failed 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"
  }'

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

Next Steps

Run Command - Execute commands synchronously
List Processes - Check background process status
Kill Process - Terminate a background process

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Use Cases

Start Web Server

Run Long Processing Job

Monitor Files

Start Development Server

Check Process Status

Kill Background Command

Next Steps

​Endpoint

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (200 OK)

​Response Fields

​Status Codes

​Use Cases

​Start Web Server

​Run Long Processing Job

​Monitor Files

​Start Development Server

​Check Process Status

​Kill Background Command

​Related

​Next Steps

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Use Cases

Start Web Server

Run Long Processing Job

Monitor Files

Start Development Server

Check Process Status

Kill Background Command

Related

Next Steps