Guest Machines
API referenceRuns

List files in a controlled run sandbox

POST/api/v1/runs/{run_id}/sandbox/control/{control_id}/files/list

Submit an asynchronous directory listing inside the controlled run sandbox, then poll the returned operation.

Relative paths resolve from /home/user; absolute paths address only the run's guest machine. A result contains at most 1,000 entries and at most 100 KiB of serialized listing data.

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

The exact credential that owns this active control may list files.

Authorization

AuthorizationBearer <token>

A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.

In: header

Path Parameters

run_id*Run Id
control_id*Control Id
Formatuuid

Header Parameters

X-Org-Id?|

Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/runs/0/sandbox/control/497f6eca-6276-4993-bfeb-53cbbbba6f08/files/list" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "request_id": "2cf666c6-b2ec-488d-be03-919cd2fb65fe",    "path": "."  }'
{  "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"}

Write a file in a controlled run sandbox POST

Submit an asynchronous whole-file UTF-8 write inside the controlled run sandbox, then poll the returned operation.

Retrieve a run sandbox operation GET

Poll a submitted command or file operation. A terminal response contains the kind-specific size-limited result or a stable failure code.