# Run a command: wait, stream or detach

`POST /v1/sandboxes/{sandbox}/commands`

**In this build:** Works on the simulator or a real VM.

**Scope:** `exec`

**CLI:** `harebox exec`

Send an `Idempotency-Key` header. A retry with the same key never repeats the action.

## Request: `CommandRequest`

| Field | Type | Notes |
|---|---|---|
| `command` (required) | `string` |  |
| `cwd` | `string` |  |
| `env` | `object` |  |
| `user` | `string` |  |
| `mode` | `string` | One of: `wait`, `stream`, `detach` |
| `timeout_seconds` | `integer` | For wait mode. Use stream or detach beyond this. |
| `stdin` | `string` |  |

## Response: 200

`Command`

| Field | Type | Notes |
|---|---|---|
| `id` (required) | `string` |  |
| `status` (required) | `string` | One of: `running`, `exited`, `killed`, `timed_out` |
| `exit_code` | `integer or null` |  |
| `stdout` | `string` |  |
| `stderr` | `string` |  |
| `truncated` | `boolean` | True when output passed 256 MiB per stream. Full output stays in the logs. |
| `started_at` | `string` |  |
| `ended_at` | `string or null` |  |

Errors follow [one format](../errors.html).