Start a command in a sandbox

Start a long-running command in a Runpod sandbox through the REST API, such as a build or test suite, and read its output later.

POST /v2/sandboxes/{id}/commands

Start a command in a sandbox

cURL

curl --request POST \
  --url https://api.runpod.io/v2/sandboxes/{id}/commands \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": [
    "sh",
    "-c",
    "cd /workspace && pytest -x"
  ],
  "timeoutSeconds": 1800
}
'

202

{
  "id": "6f1c2b8e-3d4a-4f7b-9a0e-2c5d8e1f4a7b",
  "status": "running",
  "exitCode": 0,
  "error": "<string>",
  "streamsSeparated": true,
  "outputBytes": 123,
  "truncated": true,
  "cancelRequested": true
}

Authorizations

Authorization · string · header · required

Runpod API key authentication. Generate an API key in the Runpod console and send it in the Authorization header as Bearer <api_key>. Keys are scoped to the permissions granted when created; requests may return 403 when a valid key lacks access to the requested resource or action.

Console sessions (Clerk JWTs) act for the signed-in user. To act for a team instead, also send X-Team-Id: <team_id>; it applies only when the user owns or belongs to that team, otherwise the request runs against the user's own account. API keys created inside a team already act for that team and do not need the header.

Path Parameters

id · string · required

Sandbox identifier

Body

application/json

command · string[] · required

Command to run, as an argv array. It is not interpreted by a shell; wrap in ["sh", "-c", "..."] to use shell syntax. It is not echoed back in responses, since argv often carries secrets.

Minimum array length: 1

Example:

["sh", "-c", "pytest -x"]

timeoutSeconds · integer · default: 3600

How long the command may run before it is stopped and reported as timedOut. The command also ends when the sandbox does.

Required range: 1 <= x <= 86400

Example:

1800

cwd · string

Absolute path of the directory this command runs in. It must start with /, be at most 4096 bytes and contain no control characters (U+0000 to U+001F, U+007F to U+009F). Omitted, the command runs in the sandbox's default working directory.

Pattern: ^/[^\x00-\x1f\x7f-\x9f]*$

Example:

"/workspace"

env · object

Environment variables for this command only, layered over the sandbox's own environment: a name set here replaces the sandbox's value for this command. Names must match ^[A-Za-z_][A-Za-z0-9_]*$. At most 128 variables; a name and its value together at most 128 KiB, within the 1 MiB limit on the whole request body. A value must not contain a NUL byte. Values are plain text: {{ RUNPOD_SECRET_* }} references are not resolved here and reach the command literally. Values are not logged and are not echoed back.

Show child attributes

Example:

{ "FOO": "bar" }

Response

202

application/json

The command is running.

id · string · required

Command identifier, scoped to its sandbox.

Example:

"6f1c2b8e-3d4a-4f7b-9a0e-2c5d8e1f4a7b"

status · enum<string> · required

running is the only non-terminal status.

• exited: the command ended on its own; exitCode holds its code.
• cancelled: stopped by DELETE.
• timedOut: stopped at timeoutSeconds.
• failed: never started; error says why.
• unknown: the container went away while it ran, for example because the sandbox stopped. Read the outcome from status, not exitCode.

Available options: running, exited, cancelled, timedOut, failed, unknown

exitCode · integer | null · required

The command's exit code when status is exited; null otherwise.

Example:

0

error · string | null · required

Why the command failed to start or did not finish normally, if known.

streamsSeparated · boolean · required

Whether output lines are tagged as stdout or stderr. When false, the logs streams filter is unavailable.

outputBytes · integer<int64> · required

Bytes of output captured so far.

truncated · boolean · required

True once output passed 32 MiB. Further output is dropped; the command keeps running.

cancelRequested · boolean · required

True once a cancel has been requested.