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

> Execute shell commands synchronously in the sandbox using the HopX VM Agent API. Run shell commands for system administration, package installation, and automation tasks. Learn how to use POST /commands/run endpoint to execute commands, capture output, and handle errors. Includes request examples and command execution best practices.

Execute shell commands in the sandbox and wait for completion. Commands run in `/bin/sh -c` and return stdout, stderr, and exit code.

## Endpoint

```
POST /commands/run
```

## 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       | Command timeout in seconds (default: 30)    |
| `working_dir` | string  | No       | Working directory (default: `/workspace`)   |
| `env`         | object  | No       | Environment variables for this command only |

### Example Request

Run a simple command:

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la /workspace"
  }'
```

Run with custom environment:

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "echo $MY_VAR",
    "env": {
      "MY_VAR": "hello"
    }
  }'
```

## Response

### Success (200 OK)

```json theme={null}
{
  "stdout": "total 8\ndrwxr-xr-x 2 user user 4096 Jan 28 00:00 .\ndrwxr-xr-x 3 user user 4096 Jan 28 00:00 ..\n",
  "stderr": "",
  "exit_code": 0
}
```

### Response Fields

| Field       | Type    | Description             |
| ----------- | ------- | ----------------------- |
| `stdout`    | string  | Standard output         |
| `stderr`    | string  | Standard error          |
| `exit_code` | integer | Exit code (0 = success) |

## Status Codes

| Code | Description                       |
| ---- | --------------------------------- |
| 200  | Command completed                 |
| 400  | Invalid request (missing command) |
| 401  | Unauthorized                      |
| 408  | Command timeout                   |
| 500  | Command failed                    |

## Errors

### Command Failed (500)

```json theme={null}
{
  "stdout": "",
  "stderr": "ls: cannot access '/nonexistent': No such file or directory\n",
  "exit_code": 2
}
```

**Cause:** Command execution failed.

**Fix:** Check the `stderr` field for error details and verify the command.

## Use Cases

### Install Packages

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "pip install requests numpy",
    "timeout": 120
  }'
```

### Check System Information

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "uname -a && df -h && free -h"
  }'
```

### File Operations

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "cat /workspace/data.txt | wc -l",
    "working_dir": "/workspace"
  }'
```

### Git Operations

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git clone https://github.com/user/repo.git && cd repo && git log -1",
    "working_dir": "/workspace",
    "timeout": 60
  }'
```

### Build and Test

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm install && npm test",
    "working_dir": "/workspace/project",
    "timeout": 300
  }'
```

### Pipeline Multiple Commands

```bash theme={null}
curl -X POST https://sandbox_abc123xyz.hopx.dev/commands/run \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "mkdir -p /workspace/output && python process.py && mv result.csv /workspace/output/",
    "working_dir": "/workspace"
  }'
```

## Related

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

## Next Steps

* **[Run Command in Background](/api/vm-agent/run-command-background)** - Run long-running commands
* **[Execute Code](/api/vm-agent/execute)** - Execute code directly
* **[File Operations](/api/vm-agent/read-file)** - Read and write files