machines

Execute in a session.

Changed on

Runs a command inside an existing session, inheriting its state. Requires the machine:exec scope.

post/v1/machines/{id}/sessions/{session_id}/exec

Request

Path parameters

idstring required

Machine id

session_idstring required

Session 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

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 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