Background Execution

Execute code in the background and return immediately. The code continues running asynchronously, and you can check its status using the process ID.

Endpoint

POST /execute/background

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Body Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Code to execute
`language`	string	No	Language (default: `python`)
`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/execute/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import time\nfor i in range(10):\n    print(f\"Step {i+1}/10\")\n    time.sleep(1)\nprint(\"Done!\")",
    "language": "python",
    "name": "long-task"
  }'

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	Process started
400	Invalid request
401	Unauthorized
500	Failed to start process

Check Process Status

Use the List Processes endpoint to check status:

curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "processes": [
    {
      "process_id": "proc_abc123",
      "execution_id": "exec_xyz789",
      "name": "long-task",
      "status": "running",
      "language": "python",
      "started_at": "2025-01-28T00:00:00Z",
      "stdout": "Step 1/10\nStep 2/10\n",
      "stderr": "",
      "exit_code": null
    }
  ],
  "count": 1
}

Kill Background Process

Use the Kill Process endpoint to terminate:

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"
  }'

Use Cases

Long-Running Data Processing

curl -X POST https://sandbox_abc123xyz.hopx.dev/execute/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import pandas as pd\nimport time\n\nprint(\"Processing large dataset...\")\ntime.sleep(30)\ndf = pd.read_csv(\"/workspace/large_file.csv\")\nresult = df.groupby(\"category\").sum()\nresult.to_csv(\"/workspace/result.csv\")\nprint(\"Processing complete!\")",
    "language": "python",
    "timeout": 600,
    "name": "data-processing"
  }'

Model Training

curl -X POST https://sandbox_abc123xyz.hopx.dev/execute/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "from sklearn.ensemble import RandomForestClassifier\nimport numpy as np\nimport time\n\nprint(\"Training model...\")\nX = np.random.rand(10000, 20)\ny = np.random.randint(0, 2, 10000)\n\nmodel = RandomForestClassifier(n_estimators=100)\nmodel.fit(X, y)\n\nprint(f\"Model accuracy: {model.score(X, y):.2f}\")\nprint(\"Training complete!\")",
    "language": "python",
    "timeout": 1800,
    "name": "model-training"
  }'

Monitoring Background Process

#!/bin/bash
PROCESS_ID="proc_abc123"

while true; do
  STATUS=$(curl -s https://sandbox_abc123xyz.hopx.dev/execute/processes \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
    jq -r ".processes[] | select(.process_id == \"$PROCESS_ID\") | .status")
  
  echo "Status: $STATUS"
  
  if [ "$STATUS" == "completed" ] || [ "$STATUS" == "failed" ]; then
    echo "Process finished"
    break
  fi
  
  sleep 5
done

Parallel Execution

#!/bin/bash
# Start multiple background tasks
for i in {1..5}; do
  curl -X POST https://sandbox_abc123xyz.hopx.dev/execute/background \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"code\": \"import time\\ntime.sleep(10)\\nprint('Task $i complete')\",
      \"language\": \"python\",
      \"name\": \"task-$i\"
    }"
  
  echo "Started task $i"
done

echo "All tasks started, check status:"
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

SDK: sandbox.run_code_background() - Python SDK method
CLI Code Execution - Execute code from CLI

Next Steps

List Processes - Check background process status
Kill Process - Terminate a background process
Async Execution - Execute with webhook callbacks

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Check Process Status

Kill Background Process

Use Cases

Long-Running Data Processing

Model Training

Monitoring Background Process

Parallel Execution

Next Steps

​Endpoint

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (200 OK)

​Response Fields

​Status Codes

​Check Process Status

​Kill Background Process

​Use Cases

​Long-Running Data Processing

​Model Training

​Monitoring Background Process

​Parallel Execution

​Related

​Next Steps

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Check Process Status

Kill Background Process

Use Cases

Long-Running Data Processing

Model Training

Monitoring Background Process

Parallel Execution

Related

Next Steps