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

# Run Command in Background

> Execute shell commands in the background and return immediately using the HopX VM Agent API. Run long-running shell commands without blocking, monitor process status, and retrieve results when complete. Learn how to use POST /commands/background endpoint for asynchronous command execution. Includes request examples and process management.

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

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

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

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

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

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

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

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

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

## Related

* **SDK**: [sandbox.commands.run\_background()](/sdk/python/commands#run_background) - Python SDK method
* [CLI Commands](/cli/commands/cmd) - Shell commands from CLI

## Next Steps

* **[Run Command](/api/vm-agent/run-command)** - Execute commands synchronously
* **[List Processes](/api/vm-agent/list-processes)** - Check background process status
* **[Kill Process](/api/vm-agent/kill-process)** - Terminate a background process