k7/docs/api/endpoints/exec.mdx

---
title: "Execute command"
description: "Run a command inside a sandbox"
---

Endpoint: `POST /api/v1/sandboxes/{name}/exec`

<RequestExample>
```bash cURL
curl -X POST "$BASE/api/v1/sandboxes/my-sandbox/exec?namespace=default" \
  -H "X-API-Key: $K7_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "echo Hello"}'
```
</RequestExample>

<ResponseExample>
```json Success
{
  "data": {
    "exit_code": 0,
    "stdout": "Hello\n",
    "stderr": "",
    "duration_ms": 12
  }
}
```
</ResponseExample>

<ParamField path="name" type="string" required>Sandbox name</ParamField>
<ParamField query="namespace" type="string" default="default">Namespace</ParamField>
<ParamField body="command" type="string" required>Shell command to execute</ParamField>

### Semantics

- `exit_code`: `0` on success, non-zero when the command fails.
- `stdout`/`stderr`: Raw streams captured from the process; may include newlines.
- `duration_ms`: Client-observed duration including stream lifecycle.

### Examples

```bash
curl -X POST "$BASE/api/v1/sandboxes/my-sandbox/exec?namespace=default" \
  -H "Authorization: Bearer $K7_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "apk add --no-cache curl && curl -I https://example.com"}'
```

Error example (non-zero exit):

```json
{
  "data": {
    "exit_code": 2,
    "stdout": "",
    "stderr": "some error...",
    "duration_ms": 37
  }
}
```