Run a command in a controlled run sandbox

Submit one size-limited command to the controlled run sandbox. Execution is asynchronous; poll the returned operation for the result.

Commands default to the run image's /home/user working directory, accept an optional guest-only cwd, may contain at most 20,000 characters, and may request a timeout from 1 to 600 seconds.

Combined stdout and stderr are capped at 100 KiB. An ambiguous provider outcome is reported as unknown; submit a new request only after deciding whether repeating the command is safe.

At most one operation is pending or running on a control. The control keeps at most 128 operations and 64 MiB of request and result data. A terminal result becomes unavailable as soon as it is 24 hours old; operation metadata remains.

A 202 confirms acceptance; the operation may not have started. Poll it. If it remains pending, repeat the exact payload and request_id to continue the same operation without creating another one.

Required access

Credentials: automation account, delegated token, user API key

User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.

Scope: runs:edit

The exact credential that owns this active control may submit commands.

Path Parameters

Header Parameters

Response Body

curl -X POST "https://example.com/api/v1/runs/0/sandbox/control/497f6eca-6276-4993-bfeb-53cbbbba6f08/commands" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "request_id": "b2f88fc3-a8ec-4ad2-8f40-3e36140b2584",    "command": "python -m pytest -q",    "timeout_seconds": 120  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "run_id": 0,  "control_id": "81e20d46-f0a2-4692-a3cd-ac0ccfe84ea6",  "sequence": 0,  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",  "kind": "command",  "status": "cancelled",  "failure_code": "string",  "created_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "completed_at": "2019-08-24T14:15:22Z"}