---
title: "Run a command and get its exit code and output."
method: POST
path: "/v1/sandboxes/{id}:exec"
tags: ["commands"]
---

# Run a command and get its exit code and output.

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

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}:exec`
- Auth: HTTP bearer

Waits for a sandbox that is still starting. A timeout is a result (timedOut: true, exitCode null, the output so far), never an error. For live output send `Accept: application/x-ndjson` (or stream: true): one JSON event per line, start / stdout / stderr / exit; a `continue` event gives the cursor to resume with GET .../processes/{processId}/output?follow=true. Retrying with the same Idempotency-Key never runs the command twice.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `command` string: A shell command, run as `bash -c "<command>"`: pipes, &&, redirection and globs work.
  - `argv` string[]: Or the program and its arguments, run without a shell.
  - `cwd` string: Working directory. Default /workspace.
  - `env` object: Environment for this command, merged over the sandbox's. Put secrets here, never in the command line: env is never echoed back.
  - `stdin` string: Text given to the command's standard input, which is then closed.
  - `stdinBase64` string: Bytes for standard input, base64.
  - `user` 'sandbox' | 'root': Who runs it: the sandbox user (uid 1000, HOME=/workspace), or root, through the sandbox's passwordless sudo with the same environment and PATH and HOME=/root. Saves prefixing every command with sudo.
  - `timeoutMs` integer: Default 60 s; up to 24 h.
  - `stream` boolean: Same as Accept: application/x-ndjson.

## Response `200`

Success

- object
  - `exitCode` integer, nullable, required: null when the command did not exit by itself (timedOut).
  - `stdout` string, required
  - `stderr` string, required
  - `timedOut` boolean, required
  - `stdoutTruncated` boolean
  - `stderrTruncated` boolean
  - `durationMs` integer, nullable
  - `replayed` boolean
  - `outOfMemory` object: Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why.
    - `code` 'out_of_memory', required
    - `processesKilled` integer, required: Processes of this command the out-of-memory killer ended.
    - `memoryMiB` integer, nullable, required: The sandbox's memory size.
    - `message` string, required
    - `hint` string, required: What to do: a larger memoryMiB, or a program that uses less.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)