> ## 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.

# Kill Background Process

> Terminate a running background code execution process in sandboxes using the HopX VM Agent API. Stop long-running or stuck processes to free resources and manage execution. Learn how to use DELETE /execute/kill endpoint to terminate processes by process ID. Includes request examples and process management.

Terminate a running background process. The process is killed immediately and cannot be restarted.

## Endpoint

```
DELETE /execute/kill
```

## Request

### Headers

```
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
```

### Body Parameters

| Parameter    | Type   | Required | Description        |
| ------------ | ------ | -------- | ------------------ |
| `process_id` | string | Yes      | Process ID to kill |

### Example Request

```bash theme={null}
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"
  }'
```

## Response

### Success (200 OK)

```json theme={null}
{
  "process_id": "proc_abc123",
  "status": "killed",
  "message": "Process terminated successfully"
}
```

### Response Fields

| Field        | Type   | Description                |
| ------------ | ------ | -------------------------- |
| `process_id` | string | Process ID that was killed |
| `status`     | string | New status (`killed`)      |
| `message`    | string | Confirmation message       |

## Status Codes

| Code | Description                           |
| ---- | ------------------------------------- |
| 200  | Process killed successfully           |
| 400  | Invalid request (missing process\_id) |
| 401  | Unauthorized                          |
| 404  | Process not found                     |

## Errors

### Process Not Found (404)

```json theme={null}
{
  "error": "Process not found",
  "code": "RESOURCE_NOT_FOUND"
}
```

**Cause:** The process ID doesn't exist or has already completed.

**Fix:** Verify the process ID using the List Processes endpoint.

## Use Cases

### Kill Long-Running Task

```bash theme={null}
# Start a long-running task
RESPONSE=$(curl -s -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(3600):\n    time.sleep(1)",
    "language": "python"
  }')

PROCESS_ID=$(echo "$RESPONSE" | jq -r '.process_id')
echo "Started process: $PROCESS_ID"

# ... later, kill it ...
curl -X DELETE https://sandbox_abc123xyz.hopx.dev/execute/kill \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"process_id\": \"$PROCESS_ID\"}"
```

### Kill All Running Processes

```bash theme={null}
#!/bin/bash
# Get all running processes
PROCESSES=$(curl -s https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq -r '.processes[] | select(.status == "running") | .process_id')

# Kill each one
for PROCESS_ID in $PROCESSES; do
  curl -X DELETE https://sandbox_abc123xyz.hopx.dev/execute/kill \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"process_id\": \"$PROCESS_ID\"}"
  
  echo "Killed $PROCESS_ID"
done
```

### Kill Process with Confirmation

```bash theme={null}
#!/bin/bash
PROCESS_ID="proc_abc123"

# Check if process exists
PROCESS=$(curl -s https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq ".processes[] | select(.process_id == \"$PROCESS_ID\")")

if [ -n "$PROCESS" ]; then
  STATUS=$(echo "$PROCESS" | jq -r '.status')
  NAME=$(echo "$PROCESS" | jq -r '.name')
  
  echo "Found process: $NAME (status: $STATUS)"
  echo "Killing..."
  
  curl -X DELETE https://sandbox_abc123xyz.hopx.dev/execute/kill \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"process_id\": \"$PROCESS_ID\"}"
  
  echo "Process killed"
else
  echo "Process not found"
fi
```

### Timeout and Kill

```bash theme={null}
#!/bin/bash
PROCESS_ID="proc_abc123"
TIMEOUT=60  # seconds

START_TIME=$(date +%s)

while true; do
  CURRENT_TIME=$(date +%s)
  ELAPSED=$((CURRENT_TIME - START_TIME))
  
  if [ $ELAPSED -gt $TIMEOUT ]; then
    echo "Timeout reached, killing process"
    curl -X DELETE https://sandbox_abc123xyz.hopx.dev/execute/kill \
      -H "Authorization: Bearer YOUR_JWT_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"process_id\": \"$PROCESS_ID\"}"
    break
  fi
  
  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")
  
  if [ "$STATUS" == "completed" ] || [ "$STATUS" == "failed" ]; then
    echo "Process finished naturally"
    break
  fi
  
  sleep 5
done
```

## Important Notes

<Warning>
  Killing a process terminates it immediately without cleanup. Any unsaved data or partial results will be lost.
</Warning>

* **Immediate termination** - Process is killed without graceful shutdown
* **No recovery** - Killed processes cannot be restarted
* **Check status** - Use List Processes to verify the process was killed

## Related

* **SDK**: [sandbox.kill\_process()](/sdk/python/sandbox#kill_process) - Python SDK method
* [CLI System Commands](/cli/commands/system) - System operations from CLI

## Next Steps

* **[List Processes](/api/vm-agent/list-processes)** - View all background processes
* **[Background Execution](/api/vm-agent/execute-background)** - Start new background processes
* **[Execute Code](/api/vm-agent/execute)** - Synchronous code execution