Skip to Content
Podyard

EXEC

Run commands in a pod with live NDJSON streaming.

EXEC

POST /v1/pods/{id}/exec runs a command inside a pod. The response is a NDJSON stream (one JSON object per line) that delivers stdout/stderr live, then a final exit event with the exit code and duration.

REQUEST

Headers: Authorization: Bearer <key>, Content-Type: application/json, Accept: application/x-ndjson (optional; NDJSON is the only response format).

Body:

{
  "argv": ["python3", "-c", "print('hello')"],
  "timeoutSeconds": 60,
  "workdir": "/workspace"
}
FieldTypeRequiredDescription
argvstring[]yesCommand and arguments. No shell expansion.
timeoutSecondsintnoOverride the plan default. Capped at the plan's execTimeoutSeconds.
workdirstringnoWorking directory. Defaults to /workspace.

RESPONSE_STREAM

Each line is a JSON object with a type field:

typeFieldsMeaning
stdoutdata: stringA chunk of stdout output
stderrdata: stringA chunk of stderr output
exitcode: number, durationMs: numberCommand finished; code is the process exit code
errorcode: string, message: stringPlatform error (timeout, resource limit, engine failure)

Example stream:

{"type":"stdout","data":"hello"}
{"type":"exit","code":0,"durationMs":142}

The HTTP status is 200 for the entire stream — command failure is signalled by the exit.code field, not the HTTP status. Use the stream's final exit event to determine success.

ERRORS_STREAM_LEVEL

If the platform cannot start the exec (pod not running, quota exceeded, timeout exceeded before start), the HTTP status is non-200 and the body is the standard error envelope:

{ "error": { "code": "quota_exceeded", "message": "...", "requestId": "req_...", "docsUrl": "..." } }

OUTPUT_SIZE_LIMITS

The engine retains head + tail of the output stream up to the plan's execMaxOutputBytes. When the limit is exceeded, the middle is elided and the stream includes a marker line:

{ "type": "stdout", "data": "...[truncated]..." }

WHERE_TO_GO_NEXT

  • Pods — pod lifecycle.
  • FS — file operations.
  • Errors — full error code reference.