commands

Run a command and get its exit code and output.

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.

post/v1/sandboxes/{id}:exec

Request

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

Path parameters

idstring required

Resource identifier (UUID).

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

commandstring

A shell command, run as bash -c "<command>": pipes, &&, redirection and globs work.

argvstring[]

Or the program and its arguments, run without a shell.

cwdstring

Working directory. Default /workspace.

envobject

Environment for this command, merged over the sandbox's. Put secrets here, never in the command line: env is never echoed back.

stdinstring

Text given to the command's standard input, which is then closed.

stdinBase64string

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.

timeoutMsinteger

Default 60 s; up to 24 h.

streamboolean

Same as Accept: application/x-ndjson.

Response

Success

exitCodeinteger nullable required

null when the command did not exit by itself (timedOut).

stdoutstring required
stderrstring required
timedOutboolean required
stdoutTruncatedboolean
stderrTruncatedboolean
durationMsinteger nullable
replayedboolean

Changes

No recorded changes to this operation across all 1 revision of this API.