Skip to content

Run a command

Run a shell command or transfer one file inside a Computer as the image's login user. Requires owner or root access. Inline execution allows 30 seconds and 1 MiB of output. The streamed API allows an hour with unlimited output. Direct SSH execution has neither limit.

Parameters

#
computerstringRequired
Computer name or ID.
commandstringRequired
Shell command to run as the image's login user.
stdinstring
Base64-encoded standard input, up to 1 MiB decoded. For larger input, send a non-JSON body with computer and command in the query.

Returns

#
dataobjectAlways present
Captured guest output and exit status, or an upload receipt. Downloads return file bytes; streams return output events and a final exit event.
Show 2 attributesHide attributes
alternative-1object
Captured output and exit status of a bounded guest command.
Show 2 attributesHide attributes
exit_codeintegerAlways present
Guest exit status; zero means success.
outputstring (base64) | nullAlways present
Captured output as base64-encoded bytes.
alternative-2object
A receipt for a file uploaded into the Computer.
Show 2 attributesHide attributes
bytesintegerAlways present
Number of file bytes uploaded.
pathstringAlways present
Destination path inside the Computer.
streamobject
Returned with Accept: application/x-ndjson. One event per JSON line: base64-encoded stdout or stderr, guest exit_code, or error. Errors after streaming begins can leave the command outcome unknown.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • API key permission: exec.