Acquire programmatic control of a run's sandbox

Request temporary programmatic control of the sandbox already owned by this run. Acquisition is asynchronous: poll the returned control until it is active before submitting operations.

request_id is the idempotency key. Reusing it with the same request recovers the original control; a different request conflicts.

Control adopts the sandbox image, filesystem, environment, and governed egress already selected for the agent run; callers cannot choose a new template, environment, network policy, or public port.

Only one human or programmatic control may be open for a run. A 409 means the run, sandbox, or current controller is not eligible; inspect current state rather than blindly retrying.

A 202 confirms acceptance; control may not be active yet. Poll the control. If it remains requested, repeat the exact request with the same request_id to continue acquisition without creating another control.

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

An automation account, delegated client/user pair, or user API key must be authorized for the run. Once acquired, the exact bearer credential owns the control; workspace administrators cannot rescue another credential's control through this endpoint.

Path Parameters

Header Parameters

Response Body

curl -X POST "https://example.com/api/v1/runs/0/sandbox/control" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "request_id": "50c0ac9f-b910-42d4-a62e-067f1cb11a93"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "run_id": 0,  "phase": "active",  "release_requested": true,  "requested_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "last_interaction_at": "2019-08-24T14:15:22Z",  "ended_at": "2019-08-24T14:15:22Z"}