Spacesd client
SpacesdClient: the cua-spacesd client for processes, files, the desktop and media in a sandbox.
SpacesdClient: the cua-spacesd client for processes, files, the desktop and media in a sandbox.
sandbox.spacesd() (or cua.spacesd(url, token) for any spacesd) returns a SpacesdClient. It picks native gRPC or gRPC-Web, sends the token and chunks transfers. Methods by task: processes, files, computer and media.
Python programs usually use the high-level API instead: cua_sandbox interfaces.
cua-spacesd is optional: images without it still boot and serve their declared services, and sandbox.spacesd() raises SpacesdNotAvailable. capabilities() reports what this spacesd supports (has_feature(name) checks one feature). call_json(method, json) reaches every cua.env.v1 RPC of the protocol, including those without a typed method.
SpacesdClient#Client for one cua-spacesd.
Returned by Cua.spacesd, Relay.connect, Sandbox.spacesd.
| Method | Description |
|---|---|
call_json | Calls any unary cua.env.v1 RPC with a proto3-JSON request and returns the proto3-JSON response. |
call_json_stream | Calls a server-streaming cua.env.v1 RPC and collects at most max_messages responses (or until the stream ends or timeout_ms elapses). |
capabilities | GetCapabilities (cached). |
diagnose | Runs the image self-test (SystemService.Diagnose, the checks of cua-spacesd doctor) and returns the report as JSON (schema version 1, libs/cua/proto/diagnose-report.schema.json). |
has_feature | Whether the guest supports feature. |
health | Health as proto3 JSON. |
http | Sends one plain-HTTP request to the spacesd port with this client's endpoint and credentials (through the Fleet gateway when the endpoint is a Fleet service). |
agents | Coding agents in this guest. |
attach | Attaches to a running process by pid or tag. |
click | Left click. |
cursor_position | Pointer position. |
displays | Displays as proto3 JSON ([Display]). |
double_click | Double click. |
download | Downloads path into memory. |
download_file | Downloads path to a local file. |
drag | Drags with the left button. |
get_clipboard | Clipboard text. |
hotkey | Presses a chord (["ctrl", "c"]). |
keyboard_json | Full ComputerService.Keyboard from proto3 JSON. |
list_dir | ListDir (depth 1 = direct children). |
list_processes | Guest processes as proto3 JSON ([ProcessInfo]). |
make_dir | MakeDir (with parents). |
move_to | Moves the pointer. |
open_media | Opens a media session and starts delivering encoded video frames and control events to frames. |
open_media_with_audio | SpacesdClient.open_media that also delivers audio packets to audio (set options.audio to negotiate audio tracks). |
pointer_json | Full ComputerService.Pointer from proto3 JSON. |
press | Presses one key (enter, KEY_ESCAPE, a, ...). |
remove | Remove. |
right_click | Right click. |
run | Runs a command to completion. |
screenshot | Captures a display. |
scroll | Scrolls by line deltas. |
set_clipboard | Sets clipboard text; returns the clipboard generation. |
sh | Runs line with /bin/sh -c to completion. |
spawn | Starts a command and returns its handle. |
stat | Stat. |
type_text | Types text. |
upload | Uploads bytes to path (chunked, resumable, SHA-256 verified). |
upload_file | Uploads a local file to path. |
| Accessor | Returns | Description |
|---|---|---|
endpoint() | String | Endpoint URL. |
json_methods() | Vec<String> | Methods reachable through call_json / call_json_stream. |
transport() | String | grpc or grpc-web. |
SpacesdClient.call_json#Calls any unary cua.env.v1 RPC with a proto3-JSON request and
returns the proto3-JSON response. method is the full path
(/cua.env.v1.WindowsService/ListWindows) or Service/Method.
Covers windows, accessibility, driver tools, teleport, tunnels and
every other RPC without a typed method.
async def call_json(self, method: str, request_json: str) -> str| Parameter | Type | Default |
|---|---|---|
method | String | required |
request_json | String | required |
Returns String · Async · Raises CuaError
SpacesdClient.call_json_stream#Calls a server-streaming cua.env.v1 RPC and collects at most
max_messages responses (or until the stream ends or timeout_ms
elapses).
async def call_json_stream(self, method: str, request_json: str, max_messages: int, timeout_ms: int) -> List[str]| Parameter | Type | Default |
|---|---|---|
method | String | required |
request_json | String | required |
max_messages | u32 | required |
timeout_ms | u32 | required |
Returns Vec<String> · Async · Raises CuaError
SpacesdClient.capabilities#GetCapabilities (cached).
async def capabilities(self) -> SpacesdCapabilitiesReturns SpacesdCapabilities · Async · Raises CuaError
SpacesdClient.diagnose#Runs the image self-test (SystemService.Diagnose, the checks of
cua-spacesd doctor) and returns the report as JSON (schema version
1, libs/cua/proto/diagnose-report.schema.json). options_json is a
proto3-JSON DiagnoseOptions ("{}" for the defaults: every check,
read-only). Falls back to DiagnoseOnce when the stream is cut.
async def diagnose(self, options_json: str) -> str| Parameter | Type | Default |
|---|---|---|
options_json | String | required |
Returns String · Async · Raises CuaError
SpacesdClient.has_feature#Whether the guest supports feature.
async def has_feature(self, feature: str) -> bool| Parameter | Type | Default |
|---|---|---|
feature | String | required |
Returns bool · Async · Raises CuaError
SpacesdClient.health#Health as proto3 JSON.
async def health(self) -> strReturns String · Async · Raises CuaError
SpacesdClient.http#Sends one plain-HTTP request to the spacesd port with this
client's endpoint and credentials (through the Fleet gateway when the
endpoint is a Fleet service). Used for streamable-HTTP MCP at /mcp,
for example by typed cua-driver clients. Not retried.
async def http(self, request: SpacesdHttpRequest) -> SpacesdHttpResponse| Parameter | Type | Default |
|---|---|---|
request | SpacesdHttpRequest | required |
Returns SpacesdHttpResponse · Async · Raises CuaError
SpacesdCapabilities record#SystemService.GetCapabilities, summarized. json has everything.
Returned by SpacesdClient.capabilities.
| Field | Type | Default | Description |
|---|---|---|---|
version | String | spacesd version. | |
protocol_version / protocolVersion | u32 | cua.env.v1 protocol version. | |
protocol_revision / protocolRevision | u32 | Additive contract revision. | |
os_family / osFamily | String | OS family (linux, macos, windows). | |
os_name / osName | String | OS name. | |
os_version / osVersion | String | OS version. | |
arch | String | CPU architecture. | |
hostname | String | Guest hostname. | |
initialized | bool | SystemService.Init has run. | |
features | Vec<SpacesdFeature> | Feature flags. | |
json | String | The full response as proto3 JSON. |
SpacesdFeature record#One capability flag.
| Field | Type | Default | Description |
|---|---|---|---|
name | String | Feature name (for example a11y, stream.h264, audio.desktop). | |
supported | bool | Supported in this guest. | |
limitation | Option<String> | Limitation when degraded or unsupported. | |
attributes | HashMap<String, String> | Extra attributes. |
SpacesdHttpRequest record#A plain-HTTP request to the spacesd port (for example MCP at /mcp).
| Field | Type | Default | Description |
|---|---|---|---|
method | String | Method, for example POST. | |
path | String | Absolute path under the endpoint, for example /mcp. Never a URL. | |
headers | Vec<SpacesdHttpHeader> | [] | Extra headers. Credentials (authorization, the env and Fleet claim headers) are the client's and cannot be set here. |
body | Vec<u8> | Request body (empty for none). | |
timeout_ms / timeoutMs | Option<u32> | None | Whole-request timeout; 30 s when unset. |
max_response_bytes / maxResponseBytes | Option<u64> | None | Response body cap; 16 MiB when unset. |
SpacesdHttpResponse record#The spacesd's HTTP answer.
Returned by SpacesdClient.http.
| Field | Type | Default | Description |
|---|---|---|---|
status | u16 | Status code. | |
headers | Vec<SpacesdHttpHeader> | Response headers, in order. | |
body | Vec<u8> | Response body. |
SpacesdHttpHeader record#One HTTP header (duplicates are kept in order).
| Field | Type | Default | Description |
|---|---|---|---|
name | String | Header name. | |
value | String | Header value. |