machines

Execute a command.

Changed on

Runs a command in the machine and returns exit code, stdout, and stderr. Requires the machine:exec scope.

post/v1/machines/{id}/exec

Request

Path parameters

idstring required

Machine id

Request body

backgroundboolean

Run the command detached: spawn it in the background and return its PID immediately. Use for long-lived daemons (dev server, agent runner).

cwdstring nullable
envobject
stdinstring nullable
streamboolean

Stream stdout and stderr as Server-Sent Events instead of buffering the whole run into one JSON body. The response is then text/event-stream, not MachineExecResponse: frames are event: stdout|stderr|error|exit with data: lines, and the terminal exit frame carries {"exitCode": N}. Streamed output is not capped, so this is the right path for long-running or high-volume commands.

timeoutSecondsinteger nullable
userstring nullable

Run as this user: a name from the image or a numeric uid[:gid], overriding the image's USER. Forwarded to the machine's runtime; an older runtime that cannot honour it rejects the request rather than running the command as the wrong account.

Response

Command result. Buffered JSON by default; with stream: true in the body the response is an SSE stream of event: stdout|stderr|error|exit frames instead, terminated by exit carrying {"exitCode": N}.

durationMsinteger required
exitCodeinteger required
machineIdstring required
stderrstring required

Lossy UTF-8 stderr, capped. Prefer stderrB64.

stderrB64string byte

Byte-exact stderr (base64), binary-safe and NOT truncated. Serializes as stderrB64.

stderrTruncatedboolean
stdoutstring required

Lossy UTF-8 stdout, capped (see stdout_truncated). Kept for old clients and log views; prefer stdoutB64 for byte-exact, untruncated output.

stdoutB64string byte

Byte-exact stdout (base64), binary-safe and NOT truncated. Preferred by clients that need fidelity (smol cloud exec). rename_all=camelCase serializes this as stdoutB64.

stdoutTruncatedboolean
userstring nullable

The user the command was run as, echoed back when the request set one. A client that asked for a user and does not see it here is talking to a control plane that predates the field and dropped it — which the client must treat as an error, never as "ran as the default account".

Changes

    • info

      the endpoint scheme security ApiKeyAuth was added to the API

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the media type text/event-stream for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status