Space

A connected Space: shell, files, tools, windows and the hotspot.

A Space is a connected machine. Every primitive checks the spacesd feature it needs first and fails with CapabilityMissing when the Space lacks it. Streams, teleport and agents have their own pages.

`Space`#

A connected Space. Every primitive checks the spacesd feature it needs first and fails with CapabilityMissing naming it.

Returned by Spaces.space.

Method	Description
`bash`	Runs a shell command (`/bin/sh -c`, `cmd /C` on Windows).
`call_tool`	Calls a tool of the Space's MCP service with JSON arguments.
`capabilities_json`	`GetCapabilities` of the spacesd, as proto3 JSON.
`download`	Copies a guest file or folder into `dest_dir` on this host.
`home`	The Space user's home directory.
`hotspot_status`	This Space's hotspot status.
`list_tools`	Tools of the Space's MCP service (`driver`, the default).
`request_site_login`	Signs in to a site in this Space's browser with a password the user saved in the Cua Keyvault.
`screenshot`	Captures the Space's display (the app's tile thumbnails): PNG at full size on the primary display unless `options` say otherwise.
`send_file`	Drops a host file or folder into the Space's `~/Downloads[/subdir]` (TeleportService.ReceiveFiles, per-file SHA-256).
`set_presence_settings`	Sets this Space's presence settings.
`share`	Lets `who` (a verified email or an account id) watch (`viewer`, the default) or use (`editor`) this Space through the relay.
`shares`	Who this Space is shared with, and who of them is connected now.
`start_hotspot`	Starts the reverse-SOCKS hotspot: this host serves the Space's egress.
`stop_hotspot`	Stops this Space's hotspot.
`supports`	Whether the spacesd supports `feature`.
`unshare`	Stops sharing this Space with `who` at once, or with everyone when `who` is `None`.
`upload`	Copies a host file or folder to `dest` in the Space (default: the home directory).
`write`	Writes bytes to a guest path (parents created, verified by SHA-256).
`agent_events`	Normalized events after `cursor` (0: the start), as the `agent_events` JSON (`events`, `cursor`, `caught_up`, `status`).
`agent_interrupt`	Cancels the run's turn in flight; the session stays open.
`agent_list`	Every agent run in this Space.
`agent_message`	Sends a follow-up message to a run.
`agent_start`	Starts an agent CLI (`claude-code`, `openai-codex`, ...) with a prompt, as a detached spacesd process.
`agent_status`	A run's status with the last `tail` lines of output.
`agent_stop`	Stops a run.
`app_icon`	The icon the guest desktop shows for a window's app (pass the window's `app_name`, `app_id` and `pid`), or `None` when the Space has none: show no icon then, not a placeholder.
`app_icons`	Icons for many windows' apps at once, in request order (`None`: the Space has no icon for that app; show none).
`attach_stream`	Attaches to a ticket from `Self.open_stream` and delivers the media socket's encoded frames and audio packets to the sinks as they arrive.
`close_stream`	Closes a media session opened with `Space.open_stream`.
`displays`	The Space's displays, primary first, with their resolution in physical pixels.
`join_presence`	Joins presence.
`open_stream`	Mints a media session (ticket + WebSocket URL) for another client to attach to.
`stream_session`	Opens a media session and delivers keyframe-gated encoded frames and audio to the sinks (one delivery thread; decoding stays with the caller).
`teleport`	Teleports `app`'s session into this Space.
`teleport_manifest`	What teleporting `app` (`full` or `tabs`) would move from this host.
`usage`	Memory and storage use now (cheap: poll it at a low rate while a detail is visible).
`websocket_headers`	Headers a media WebSocket to this Space needs besides its ticket.
`window_thumbnail`	A small JPEG preview of one of the Space's windows (`window_id` and `epoch` from `windows`), at most `max_dimension` px, reused for a few seconds (the SDK's preview cache); `None` when the guest captured nothing.
`windows`	Streamable windows, optionally of one app.

Accessor	Returns	Description
`id()`	`String`	Id.
`info()`	`SpaceInfo`	The registry entry.
`services()`	`Vec<String>`	The MCP services this Space exposes: `driver` when its spacesd has the tool registry, then every declared service (reached over generic MCP; no spacesd needed).

`Space.bash`#

Runs a shell command (/bin/sh -c, cmd /C on Windows).

async def bash(self, command: str, timeout_ms: Optional[int]) -> SpaceBashResult

Parameter	Type	Default
`command`	`String`	required
`timeout_ms`	`Option<u64>`	required

Returns SpaceBashResult · Async · Raises CuaError

`Space.call_tool`#

Calls a tool of the Space's MCP service with JSON arguments.

async def call_tool(self, tool: str, arguments_json: Optional[str], service: Optional[str], timeout_ms: Optional[int]) -> SpaceToolResult

Parameter	Type	Default
`tool`	`String`	required
`arguments_json`	`Option<String>`	required
`service`	`Option<String>`	required
`timeout_ms`	`Option<u64>`	required

Returns SpaceToolResult · Async · Raises CuaError

`Space.capabilities_json`#

GetCapabilities of the spacesd, as proto3 JSON.

def capabilities_json(self) -> str

Returns String · Raises CuaError

`Space.download`#

Copies a guest file or folder into dest_dir on this host. Existing host files are never replaced: a name that is taken lands as name (1).ext, and the report's dest is the path used. Use download_file on the Space's environment to write one exact path.

async def download(self, remote_path: str, dest_dir: str) -> SpaceTransferReport

Parameter	Type	Default
`remote_path`	`String`	required
`dest_dir`	`String`	required

Returns SpaceTransferReport · Async · Raises CuaError

`Space.home`#

The Space user's home directory.

async def home(self) -> str

Returns String · Async · Raises CuaError

`Space.hotspot_status`#

This Space's hotspot status.

async def hotspot_status(self) -> List[SpaceHotspotStatus]

Returns Vec<SpaceHotspotStatus> · Async · Raises CuaError

`Space.list_tools`#

Tools of the Space's MCP service (driver, the default).

async def list_tools(self, service: Optional[str]) -> List[SpaceToolInfo]

Parameter	Type	Default
`service`	`Option<String>`	required

Returns Vec<SpaceToolInfo> · Async · Raises CuaError

`Space.request_site_login`#

Signs in to a site in this Space's browser with a password the user saved in the Cua Keyvault. The first call files a request (status == "pending" with a request_id); the user approves it in Cua, then call again with that request_id and the Keyvault types the login through the Space's cua-driver (status == "filled"). A declined request is an error. The password never reaches the caller.

async def request_site_login(self, url: str, options: Optional[SiteLoginOptions]) -> SiteLoginReport

Parameter	Type	Default
`url`	`String`	required
`options`	`Option<SiteLoginOptions>`	required

Returns SiteLoginReport · Async · Raises CuaError

`Space.screenshot`#

Captures the Space's display (the app's tile thumbnails): PNG at full size on the primary display unless options say otherwise. Fails with CapabilityMissing (spacesd) when the image runs no cua-spacesd.

async def screenshot(self, options: Optional[ScreenshotOptions]) -> Screenshot

Parameter	Type	Default
`options`	`Option<ScreenshotOptions>`	required

Returns Screenshot · Async · Raises CuaError (CapabilityMissing)

`Space.send_file`#

Drops a host file or folder into the Space's ~/Downloads[/subdir] (TeleportService.ReceiveFiles, per-file SHA-256).

async def send_file(self, local_path: str, options: SpaceSendFileOptions) -> SpaceSendFileReport

Parameter	Type	Default
`local_path`	`String`	required
`options`	`SpaceSendFileOptions`	required

Returns SpaceSendFileReport · Async · Raises CuaError

`Space.set_presence_settings`#

Sets this Space's presence settings. cursor_probe: whether cua-spacesd may read the real cursor shape by briefly moving the idle guest pointer to a participant's position (on by default); None leaves it unchanged.

async def set_presence_settings(self, cursor_probe: Optional[bool] = None) -> None

Parameter	Type	Default
`cursor_probe`	`Option<bool>`	`None`

Async · Raises CuaError

`Space.share`#

Lets who (a verified email or an account id) watch (viewer, the default) or use (editor) this Space through the relay. A Space that is not a host is attached to the relay on its first share.

async def share(self, who: str, role: Optional[str]) -> SpaceShares

Parameter	Type	Default
`who`	`String`	required
`role`	`Option<String>`	required

Returns SpaceShares · Async · Raises CuaError

`Space.shares`#

Who this Space is shared with, and who of them is connected now.

async def shares(self) -> SpaceShares

Returns SpaceShares · Async · Raises CuaError

`Space.start_hotspot`#

Starts the reverse-SOCKS hotspot: this host serves the Space's egress. set_system_proxy points the guest's proxy settings at it (default false here).

async def start_hotspot(self, set_system_proxy: Optional[bool], bypass: Optional[List[str]]) -> SpaceHotspotStatus

Parameter	Type	Default
`set_system_proxy`	`Option<bool>`	required
`bypass`	`Option<Vec<String>>`	required

Returns SpaceHotspotStatus · Async · Raises CuaError

`Space.stop_hotspot`#

Stops this Space's hotspot. Returns the stopped Space ids.

async def stop_hotspot(self) -> List[str]

Returns Vec<String> · Async · Raises CuaError

`Space.supports`#

Whether the spacesd supports feature.

def supports(self, feature: str) -> bool

Parameter	Type	Default
`feature`	`String`	required

Returns bool

`Space.unshare`#

Stops sharing this Space with who at once, or with everyone when who is None.

async def unshare(self, who: Optional[str]) -> SpaceShares

Parameter	Type	Default
`who`	`Option<String>`	required

Returns SpaceShares · Async · Raises CuaError

`Space.upload`#

Copies a host file or folder to dest in the Space (default: the home directory).

async def upload(self, local_path: str, dest: Optional[str]) -> SpaceTransferReport

Parameter	Type	Default
`local_path`	`String`	required
`dest`	`Option<String>`	required

Returns SpaceTransferReport · Async · Raises CuaError

`Space.write`#

Writes bytes to a guest path (parents created, verified by SHA-256).

async def write(self, path: str, content: bytes) -> SpaceWriteReport

Parameter	Type	Default
`path`	`String`	required
`content`	`Vec<u8>`	required

Returns SpaceWriteReport · Async · Raises CuaError

`SpaceBashResult` record#

Output of Space.bash.

Returned by Space.bash.

Field	Type	Description
`stdout`	`String`	Stdout.
`stderr`	`String`	Stderr.
`exit_code` / `exitCode`	`Option<i32>`	Exit code (absent when signalled or timed out).
`signal`	`Option<String>`	Signal name, when killed by one.
`timed_out` / `timedOut`	`bool`	Hit the timeout.
`error`	`Option<String>`	Launch error.
`rendered`	`String`	The `space_bash` tool text (`stdout`, `[stderr]`, `[exit N]`).

`SpaceWriteReport` record#

Result of Space.write.

Returned by Space.write.

Field	Type	Description
`path`	`String`	Guest path.
`bytes`	`u64`	Bytes.
`sha256`	`String`	SHA-256 verified in the Space.

`SpaceTransferReport` record#

Result of Space.upload / Space.download.

Returned by Space.download, Space.upload.

Field	Type	Description
`source`	`String`	Source.
`dest`	`String`	Destination.
`kind`	`String`	`file` or `folder`.
`files`	`u64`	Files written.
`directories`	`u64`	Directories created (uploads).
`bytes`	`u64`	Total bytes.
`sha256`	`Option<String>`	SHA-256 (single files).
`verified`	`bool`	Every file verified by SHA-256.

`SpaceSendFileOptions` record#

Options for Space.send_file.

Field	Type	Default	Description
`target_directory` / `targetDirectory`	`Option<String>`	`None`	Downloads subdirectory (`None` = `~/Downloads`), or a `~/Downloads/…` path.
`respect_ignore_files` / `respectIgnoreFiles`	`bool`	`true`	Honor ignore files when sending a folder.
`conflict`	`Option<String>`	`None`	When a file of the same name is already there: `rename` (default, keeps both as `name (1).ext`), `skip`, or `overwrite` to replace it.

`SpaceSendFileReport` record#

Result of Space.send_file.

Returned by Space.send_file.

Field	Type	Description
`source`	`String`	Host source.
`destination`	`String`	Transfer root in the guest.
`dest`	`String`	Where the file or folder landed.
`kind`	`String`	`file` or `folder`.
`files`	`Vec<SpaceSentFile>`	Files placed.
`bytes`	`u64`	Total bytes.
`skipped_by_ignorefiles` / `skippedByIgnorefiles`	`Vec<String>`	Paths left out by ignore rules (first 200).
`skipped_by_guest` / `skippedByGuest`	`Vec<String>`	Paths the guest skipped.
`verified`	`bool`	Every hash matched.

`SpaceSentFile` record#

One file placed by Space.send_file.

Field	Type	Description
`path`	`String`	Guest path.
`size`	`u64`	Bytes.
`sha256`	`String`	SHA-256, verified on both ends.

`SpaceWindow` record#

A streamable window.

Returned by Space.windows.

Field	Type	Description
`window_id` / `windowId`	`String`	Window handle.
`epoch`	`u64`	Generation.
`title`	`String`	Title.
`app_name` / `appName`	`String`	App name.
`app_id` / `appId`	`String`	App id.
`pid`	`u32`	Pid.
`bounds`	`Vec<f64>`	`[x, y, width, height]` in logical points.
`on_screen` / `onScreen`	`bool`	On screen.
`focused`	`bool`	Focused.
`available`	`bool`	Streamable now.
`limitation`	`String`	Why not.

`SpaceToolInfo` record#

A tool of a Space's MCP service.

Returned by Space.list_tools.

Field	Type	Description
`name`	`String`	Name.
`description`	`String`	Description.
`input_schema_json` / `inputSchemaJson`	`String`	Input JSON Schema.
`read_only` / `readOnly`	`bool`	Read-only.
`destructive`	`bool`	Destructive.

`SpaceToolResult` record#

The result of a tool call (MCP content as JSON).

Returned by Space.call_tool, Spaces.call_tool_json.

Field	Type	Description
`content_json` / `contentJson`	`String`	MCP content parts as a JSON array.
`structured_json` / `structuredJson`	`Option<String>`	Structured content as JSON, when present.
`is_error` / `isError`	`bool`	The tool failed.
`text`	`String`	Concatenated text parts.
`meta_json` / `metaJson`	`Option<String>`	The result's `_meta` as JSON, when present.

`SpaceHotspotStatus` record#

Hotspot state.

Returned by Space.hotspot_status, Space.start_hotspot.

Field	Type	Description
`space`	`String`	Space.
`state`	`String`	`stopped`, `waiting_for_peer` or `active`.
`hotspot_id` / `hotspotId`	`String`	Hotspot id.
`socks_address` / `socksAddress`	`String`	Guest SOCKS address.
`active_connections` / `activeConnections`	`u32`	Open relayed connections.
`bytes_out` / `bytesOut`	`u64`	Bytes out of the guest.
`bytes_in` / `bytesIn`	`u64`	Bytes into the guest.
`served_here` / `servedHere`	`bool`	Served by the process that owns the Spaces runtime.

`SiteLoginOptions` record#

Options for Space.request_site_login.

Field	Type	Default	Description
`username`	`Option<String>`	`None`	Which saved username, when the site has several.
`agent`	`Option<String>`	`None`	The persistent agent asking (shown to the user in the approval).
`session`	`Option<String>`	`None`	cua-driver lifecycle session of the tab to sign in.
`target_id` / `targetId`	`Option<String>`	`None`	cua-driver browser target id (from `get_browser_state`).
`tab_id` / `tabId`	`Option<String>`	`None`	cua-driver tab id (from `get_browser_state`).
`request_id` / `requestId`	`Option<String>`	`None`	The request id a previous call returned (the retry after approval).
`wait_secs` / `waitSecs`	`Option<u32>`	`None`	Seconds to wait for the user's decision on a retry (default 20, at most 120).

`SiteLoginReport` record#

What Space.request_site_login did. Never the password.

Returned by Space.request_site_login.

Field	Type	Description
`status`	`String`	`pending` (the user has not approved yet) or `filled`.
`request_id` / `requestId`	`Option<String>`	The Keyvault request to retry with, while pending.
`site`	`Option<String>`	Site of the saved login (`github.com`), once filled.
`origin`	`Option<String>`	The origin signed in to, once filled.
`username_hint` / `usernameHint`	`Option<String>`	The username, masked (`a***@example.test`).
`submitted`	`bool`	The form was submitted.
`page_url` / `pageUrl`	`Option<String>`	The tab's URL after the fill.
`session`	`Option<String>`	The tab it signed in (cua-driver ids), to keep using it.
`target_id` / `targetId`	`Option<String>`	See `session`.
`tab_id` / `tabId`	`Option<String>`	See `session`.

`SpaceRelayRegistration` record#

A Space published on the relay (Spaces.relay_register).

Returned by Spaces.relay_register.

Field	Type	Description
`space`	`String`	The Space.
`relay_space` / `relaySpace`	`String`	How the account's other devices reach it: `relay:<machine>`.
`machine`	`String`	The relay machine id.
`url`	`String`	The relay URL of the machine.
`online`	`bool`	Connected to the relay now.

`SpaceShareEntry` record#

One account a Space is shared with.

Field	Type	Description
`who`	`String`	The email or account id, as shared.
`role`	`String`	`viewer` or `editor`.
`connected`	`bool`	Connected through the relay right now.

`SpaceShares` record#

Who a Space is shared with.

Returned by Space.share, Space.shares, Space.unshare.

Field	Type	Description
`space`	`String`	The Space.
`machine`	`String`	The relay machine it is shared as (empty when not shared).
`invitee_space` / `inviteeSpace`	`String`	What the people it is shared with open (`relay:<machine>`).
`url`	`String`	The relay URL of the machine.
`online`	`bool`	The machine is on the relay now.
`shares`	`Vec<SpaceShareEntry>`	The accounts and their roles.

`SpacesHost` record#

One of your machines that provides Spaces (Spaces.hosts).

Returned by Spaces.hosts.

Field	Type	Description
`id`	`String`	What `on="host:<id>"` takes: the relay machine id, or the name a direct host was added as.
`name`	`String`	Its name.
`via`	`String`	`relay` or `direct`.
`online`	`bool`	It answered.
`os`	`String`	Its operating system (`macos`, `linux`, `windows`), when it answered.
`limits`	`Vec<SpacesHostLimit>`	Its limits, when it answered.

`SpacesHostLimit` record#

One limit of a host that provides Spaces and how much of it is used.

Field	Type	Description
`resource`	`String`	`spaces` (every Space it provides) or `macos_vms`.
`used`	`u32`	In use now.
`limit`	`u32`	The limit (0: none).
`reason`	`String`	Why the limit exists, for people.

Space

Space#

Space.bash#

Space.call_tool#

Space.capabilities_json#

Space.download#

Space.home#

Space.hotspot_status#

Space.list_tools#

Space.request_site_login#

Space.screenshot#

Space.send_file#

Space.set_presence_settings#

Space.share#

Space.shares#

Space.start_hotspot#

Space.stop_hotspot#

Space.supports#

Space.unshare#

Space.upload#

Space.write#

SpaceBashResult record#

SpaceWriteReport record#

SpaceTransferReport record#

SpaceSendFileOptions record#

SpaceSendFileReport record#

SpaceSentFile record#

SpaceWindow record#

SpaceToolInfo record#

SpaceToolResult record#

SpaceHotspotStatus record#

SiteLoginOptions record#

SiteLoginReport record#

SpaceRelayRegistration record#

SpaceShareEntry record#

SpaceShares record#

SpacesHost record#

SpacesHostLimit record#

Space#

Space.bash#

Space.call_tool#

Space.capabilities_json#

Space.download#

Space.home#

Space.hotspot_status#

Space.list_tools#

Space.request_site_login#

Space.screenshot#

Space.send_file#

Space.set_presence_settings#

Space.share#

Space.shares#

Space.start_hotspot#

Space.stop_hotspot#

Space.supports#

Space.unshare#

Space.upload#

Space.write#

SpaceBashResult record#

SpaceWriteReport record#

SpaceTransferReport record#

SpaceSendFileOptions record#

SpaceSendFileReport record#

SpaceSentFile record#

SpaceWindow record#

SpaceToolInfo record#

SpaceToolResult record#

SpaceHotspotStatus record#

SiteLoginOptions record#

SiteLoginReport record#

SpaceRelayRegistration record#

SpaceShareEntry record#

SpaceShares record#

SpacesHost record#

SpacesHostLimit record#

`Space`#

`Space.bash`#

`Space.call_tool`#

`Space.capabilities_json`#

`Space.download`#

`Space.home`#

`Space.hotspot_status`#

`Space.list_tools`#

`Space.request_site_login`#

`Space.screenshot`#

`Space.send_file`#

`Space.set_presence_settings`#

`Space.share`#

`Space.shares`#

`Space.start_hotspot`#

`Space.stop_hotspot`#

`Space.supports`#

`Space.unshare`#

`Space.upload`#

`Space.write`#

`SpaceBashResult` record#

`SpaceWriteReport` record#

`SpaceTransferReport` record#

`SpaceSendFileOptions` record#

`SpaceSendFileReport` record#

`SpaceSentFile` record#

`SpaceWindow` record#

`SpaceToolInfo` record#

`SpaceToolResult` record#

`SpaceHotspotStatus` record#

`SiteLoginOptions` record#

`SiteLoginReport` record#

`SpaceRelayRegistration` record#

`SpaceShareEntry` record#

`SpaceShares` record#

`SpacesHost` record#

`SpacesHostLimit` record#

`Space`#

`Space.bash`#

`Space.call_tool`#

`Space.capabilities_json`#

`Space.download`#

`Space.home`#

`Space.hotspot_status`#

`Space.list_tools`#

`Space.request_site_login`#

`Space.screenshot`#

`Space.send_file`#

`Space.set_presence_settings`#

`Space.share`#

`Space.shares`#

`Space.start_hotspot`#

`Space.stop_hotspot`#

`Space.supports`#

`Space.unshare`#

`Space.upload`#

`Space.write`#

`SpaceBashResult` record#

`SpaceWriteReport` record#

`SpaceTransferReport` record#

`SpaceSendFileOptions` record#

`SpaceSendFileReport` record#

`SpaceSentFile` record#

`SpaceWindow` record#

`SpaceToolInfo` record#

`SpaceToolResult` record#

`SpaceHotspotStatus` record#

`SiteLoginOptions` record#

`SiteLoginReport` record#

`SpaceRelayRegistration` record#

`SpaceShareEntry` record#

`SpaceShares` record#

`SpacesHost` record#

`SpacesHostLimit` record#