Sign in

v4

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-05-09283767.7 KB
exec

Execute a command inside a VM

Runs command inside the VM. Response shape is determined by the client's Accept header:

  • Accept: application/json (default, omitted, or */*): buffered ExecVMResponse — the server collects all output and returns a single JSON object once the command exits. Per-stream output is capped at 4 MiB; overflow bytes are dropped and signalled via stdoutTruncated / stderrTruncated.
  • Accept: application/x-ndjson: newline-delimited stream of ExecEvents — zero or more stdout/stderr chunks followed by exactly one terminal exit event. Use this for incremental output (long builds, test runners, live logs). No server-side cap.

Both modes share the same request body. timeoutSec bounds server-side execution; clients should set their own HTTP timeout in addition.

502 responses are transient (the upstream VM host is unreachable or returned an error). The SDK's run() helper does NOT auto-retry these by default: exec is not idempotent, so if a 502 hides a successful exec a retry may run the command twice. Callers opt in with max_retries=N per call.

post/v1/vms/{id}/exec

Request body

commandstring[] required

Argv-style command. First element must be non-empty. For shell strings, wrap as ["sh", "-c", "<string>"].

timeoutSecinteger

Server-side execution timeout in seconds. Must be positive when provided; omit to use the server default.

stdinstring

Optional base64-encoded stdin blob, written to the child's stdin before the process starts reading much and then closed. Streaming stdin is not supported — pipe from a file inside the guest if you need that shape.

Response

Command completed. application/json (default) returns a single ExecVMResponse; application/x-ndjson returns an event stream terminated by one exit event.

exitCodeinteger required
stdoutstring required
stderrstring required
timedOutboolean required
stdoutTruncatedboolean required

True if the collector dropped stdout bytes past the 4 MiB cap.

stderrTruncatedboolean required

True if the collector dropped stderr bytes past the 4 MiB cap.

durationMsinteger required