---
search:
  tags:
    - Sandboxes
    - POST
seo:
  description: >-
    Runs a command and waits for it, up to timeout_ms. A retry with the same…
    Reference for the POST /v1/sandboxes/{id}/exec endpoint in the Ibby API.
sidebar:
  label: Run a command
  badge: POST
title: Run a command
type: openapi-operation
---
Runs a command and waits for it, up to `timeout_ms`. A retry with the same `Idempotency-Key` gets 409 `in_progress` while the command runs, and the outcome with `stdout` null once it has finished.

`POST /v1/sandboxes/{id}/exec`

**Request body** (`application/json`, required)

- `command` (string[], required) — The program and its arguments, as an argv array. No shell runs unless the caller runs one.
- `cwd` (string) — The directory to run in. Defaults to the sandbox's \`workdir\`.
- `env` (object) — Up to 8 environment variables. A name that looks like a secret is refused with 400 \`env\_name\_refused\`.
- `timeout_ms` (integer) — How long the command may run, in milliseconds. At most 120000, and that when absent. When it passes, the result is \`timed\_out\`.

Request body example:

```json
{
  "command": [
    "python",
    "-c",
    "print(1)"
  ],
  "cwd": "string",
  "env": {
    "property1": "string",
    "property2": "string"
  },
  "timeout_ms": 120000
}
```

**Responses**

- `200` — The command ended or timed out.
- `400` — \`invalid\_request\`: The request does not match the contract. \`env\_name\_refused\`: An \`env\` name looks like a secret, which a sandbox may not receive.
- `401` — \`unauthorized\`: The API key is missing, unknown or revoked.
- `404` — \`not\_found\`: No such resource in this key's lane. Another lane's ids are not found either.
- `409` — \`sandbox\_stopped\`: The sandbox has stopped: its lifetime or size limit was reached, or it was removed. \`in\_progress\`: A call with this \`Idempotency-Key\` is still running, or the sandbox is still being created. Retry later. \`idempotency\_mismatch\`: The \`Idempotency-Key\` was used before with a different body.
- `500` — \`internal\_error\`: The platform failed. A retry may succeed; for a call that creates or writes, retry with the same Idempotency-Key.
- `503` — \`unavailable\`: A service behind the API could not be reached. Retry after a short wait; for a call that creates or writes, with the same Idempotency-Key.

Response example, 200:

```json
{
  "exit_code": 0,
  "outcome": "exited",
  "stdout": "string",
  "stdout_truncated": true
}
```