---
title: "Execute a command"
method: POST
path: "/v1/sandboxes/{id}/exec"
tags: ["Sandboxes"]
---

# Execute a command

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

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/sandboxes/{id}/exec`
- Auth: HTTP bearer

Queues one process inside the sandbox. The sandbox can execute multiple commands over its lifetime.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- SandboxExecRequest
  - `command` string[], required: Process argument vector. No shell parsing is performed.
  - `cwd` string: Optional canonical absolute POSIX working directory.
  - `env` object: Nonsecret environment values. Values equal to any retained tenant secret are rejected. Use sandbox secrets for confidential values.
  - `timeout_s` integer: Process timeout no greater than the sandbox maximum lifetime.
  - `stdin` boolean: Enable framed stdin writes for this process.
  - `tty` boolean: Allocate a controlling terminal with merged stdout and stderr. Requires stdin and explicit rows and cols.
  - `rows` integer
  - `cols` integer

## Response `202`

Accepted

- SandboxExec
  - `id` string, required
  - `sandbox_id` string, required
  - `spec` SandboxExecRequest, required
    - `command` string[], required: Process argument vector. No shell parsing is performed.
    - `cwd` string: Optional canonical absolute POSIX working directory.
    - `env` object: Nonsecret environment values. Values equal to any retained tenant secret are rejected. Use sandbox secrets for confidential values.
    - `timeout_s` integer: Process timeout no greater than the sandbox maximum lifetime.
    - `stdin` boolean: Enable framed stdin writes for this process.
    - `tty` boolean: Allocate a controlling terminal with merged stdout and stderr. Requires stdin and explicit rows and cols.
    - `rows` integer
    - `cols` integer
  - `state` 'queued' | 'dispatching' | 'running' | 'completed' | 'failed' | 'cancelled' | 'lost', required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `dispatched_at` string, date-time, nullable
  - `deadline_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `exit_code` integer, nullable: Process exit code when known. A completed process can have a nonzero exit code.
  - `failure_code` string: Failure to start or maintain execution, separate from a process exit code.
  - `output_sequence` integer, required
  - `stdout_bytes` integer, required
  - `stderr_bytes` integer, required
  - `final_output_sequence` integer, nullable
  - `cancel_requested_at` string, date-time, nullable
  - `cancel_reason` string

## Other responses

- `default`: Error. The code, message, and fix fields describe the rejection and its remedy.

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)