Space

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

Connected machine primitives; missing spacesd features return CapabilityMissing.

`Space`#

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

Returned by Space.fork, Spaces.fork, 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: PNG at full size on the primary display unless `options` say otherwise (for a small preview, `Space.thumbnail` reads the shared cache instead).
`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.
`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`.
`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.
`checkpoint`	Saves this Space's state as checkpoint `checkpoint` (the sandbox API's `Sandboxes.checkpoint`): it keeps running, and `Spaces.fork(checkpoint, name)` (this machine) or `Spaces.create` with image `checkpoint:<name>` (any of your machines) starts new Spaces from it.
`close_stream`	Closes a media session opened with `Space.open_stream`.
`delete_service`	Stops a service and forgets it (its logs go too).
`displays`	The Space's displays, primary first, with their resolution in physical pixels.
`fork`	Starts Space `name`, a fork of this one (with its memory when it is running), and returns it connected.
`forward`	Forwards a free loopback port on this machine to guest `port` over this Space's own connection (cua-spacesd's tunnel): the same path its calls take, so a Space one of your machines provides on your LAN is reached directly, and never through a port opened on that machine's network.
`join_presence`	Joins presence.
`join_presence_for`	Joins presence for the window being watched.
`kept_services`	This Space's services.
`open_stream`	Mints a media session (ticket + WebSocket URL) for another client to attach to.
`put_service`	Keeps a command running in this Space (replacing a service of that name): restarted by its policy when it ends or fails its health check, started when the Space boots, its output kept in a log file.
`restart_service`	Restarts a service.
`route`	Which way this Space's calls go now (see `super.spacesd.SpacesdClient.route`): `local …`, `direct …`, `relay …`, `mesh direct <ip:port> rtt <ms> ms`, `mesh relayed` or `cloud`; empty when the Space runs no cua-spacesd.
`service_logs`	The end of a service's log (`tail_bytes` `None`: 64 KiB).
`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.
`spacesd`	The cua-spacesd client over the connection this Space authenticated.
`start_service`	Starts a stopped service.
`stop_service`	Stops a service and keeps it stopped (also across a reboot).
`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.
`thumbnail`	The Space's latest thumbnail (a small JPEG of its primary display) from the cache every client on this machine shares: returned at once when it is younger than `max_age_ms` (unset: any age), else captured fresh through cua-spacesd and kept for the next caller.
`transport`	What carries this Space's calls, for a badge: `mesh` (end to end) or `relay_https` (the relay can read the session in transit; with `fallback_reason` when the mesh was wanted), or `local`, `direct`, `cloud`.
`unshare`	Stops sharing this Space with `who` at once, or with everyone when `who` is `None`.
`usage`	Processor, 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`	Connection-time snapshot; never refreshed. With spacesd, handshake `os`, `os_name`, `os_pretty_name` replace record values; missing/unknown families clear them. Other fields and non-spacesd services retain registry/discovery values. `Spaces.list()`/`Spaces.resolve()` remain record views.
`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: PNG at full size on the primary display unless options say otherwise (for a small preview, Space.thumbnail reads the shared cache instead). 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.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.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	Default	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.
`origin`	`Option<SpaceWindowOrigin>`	`None`	Where the picture comes from when another Space shows this window here (`stream_space_window`); `None` for the Space's own windows. Open it like any window: `Space.open_stream` with its `window_id` streams it straight from the origin when you may reach it.

`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.

`NetworkEvent` record#

One kind of connection a Space tried and its network refused (Spaces.network_log).

Returned by Spaces.network_log.

Field	Type	Description
`reason`	`String`	Why: `platform:metadata`, `default:lan`, `default:host-loopback`, `user:deny`, `default:none`, ...
`dst`	`String`	Where to (`169.254.169.254:80`, or the rule's network where only the host's firewall counted it).
`proto`	`Option<String>`	`tcp` or `udp` when known.
`count`	`u64`	How many times.
`last_unix` / `lastUnix`	`Option<u64>`	When the last one was refused (Unix seconds), when known.

`SharedBase` record#

A base image several Spaces share copy-on-write (a container image's layers, the image a VM disk was cloned from).

Field	Type	Description
`key`	`String`	Which base: Spaces with the same key share the same blocks.
`image`	`String`	The image reference it came from (`ghcr.io/trycua/linux:24.04`).
`bytes`	`Option<u64>`	What it takes on this computer, once for all its Spaces; absent when the runtime cannot tell it apart from the Spaces' own data.
`shared_with` / `sharedWith`	`u32`	Local Spaces that use it, this one included.

`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`.

`SpaceCreatingElsewhere` record#

A Space another of your computers is creating (SpaceList.creating).

Field	Type	Description
`machine_id` / `machineId`	`String`	The computer's relay machine id.
`machine_name` / `machineName`	`String`	The computer's name.
`name`	`String`	The Space's name.
`os`	`String`	`macos`, `linux`, `windows`, or empty when unknown.
`phase`	`String`	The create's phase (`preparing`, `pulling`, `booting`, ...).
`percent`	`u32`	How far along the whole create is, 0 to 100.
`updated_at_ms` / `updatedAtMs`	`u64`	When the computer published it, unix ms.

`SpaceWindowOrigin` record#

The Space a window row's picture comes from (SpaceWindow.origin).

Field	Type	Description
`space_id` / `spaceId`	`String`	The origin Space (canonical id).
`name`	`String`	Its name.
`os`	`String`	Its OS (`macos`, `linux`, `windows`, or empty).
`window_id` / `windowId`	`String`	The window's handle in the origin.

`EgressEnforcement` enum#

Where a Space's egress policy is enforced (SpaceInfo.egress_enforced).

EgressEnforcement.HOST

Variant	Description
`Host`	By the host the Space runs on, outside the guest: nothing in the guest, root included, can change it.

Windows, icons and displays#

app_icons answers a whole window list in one call: cached icons come from memory or $CUA_HOME/cache/icons, and every miss costs one guest round trip. thumbnail is the Space's latest small preview from the cache every client on the machine shares ($CUA_HOME/cache/thumbnails, kept fresh by the daemon while someone asks). window_thumbnail previews one window, reused for a few seconds. displays lists the displays with their resolution and usage the memory and storage use.

Methods of Space.

`Space.app_icons`#

Icons for many windows' apps at once, in request order (None: the Space has no icon for that app; show none). Answered by the SDK's one icon cache (memory, then $CUA_HOME/cache/icons, keyed by the app and the Space's image, never the pid); every miss costs one guest round trip for the whole batch. macOS renders the app bundle of the pid; Linux reads the .desktop entry's Icon= from the icon theme; Windows has none.

async def app_icons(self, requests: List[SpaceAppIconRequest]) -> List[Optional[SpaceAppIcon]]

Parameter	Type	Default
`requests`	`Vec<SpaceAppIconRequest>`	required

Returns Vec<Option<SpaceAppIcon>> · Async · Raises CuaError

`Space.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. A window list should ask Space.app_icons once for all its windows instead.

async def app_icon(self, app_name: str, app_id: str, pid: int) -> Optional[SpaceAppIcon]

Parameter	Type	Default
`app_name`	`String`	required
`app_id`	`String`	required
`pid`	`u32`	required

Returns Option<SpaceAppIcon> · Async · Raises CuaError

`Space.thumbnail`#

The Space's latest thumbnail (a small JPEG of its primary display) from the cache every client on this machine shares: returned at once when it is younger than max_age_ms (unset: any age), else captured fresh through cua-spacesd and kept for the next caller. When that capture fails, the older one comes back (captured_at_ms says how old). Asking keeps the daemon refreshing running Spaces' thumbnails in the background for a while (about every 90 s).

async def thumbnail(self, max_age_ms: Optional[int]) -> SpaceThumbnail

Parameter	Type	Default
`max_age_ms`	`Option<u64>`	required

Returns SpaceThumbnail · Async · Raises CuaError

`Space.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.

async def window_thumbnail(self, window_id: str, epoch: int, max_dimension: int) -> Optional[bytes]

Parameter	Type	Default
`window_id`	`String`	required
`epoch`	`u64`	required
`max_dimension`	`u32`	required

Returns Option<Vec<u8>> · Async · Raises CuaError

`Space.displays`#

The Space's displays, primary first, with their resolution in physical pixels.

async def displays(self) -> List[SpaceDisplay]

Returns Vec<SpaceDisplay> · Async · Raises CuaError

`Space.usage`#

Processor, memory and storage use now (cheap: poll it at a low rate while a detail is visible).

async def usage(self) -> SpaceUsage

Returns SpaceUsage · Async · Raises CuaError

`SpaceAppIcon` record#

An app icon from Space.app_icons: the icon the guest desktop uses, normalized by the SDK's icon cache.

Returned by Space.app_icon, Space.app_icons.

Field	Type	Description
`bytes`	`Vec<u8>`	The 64 px PNG (2x), or an SVG the guest could not rasterize.
`content_type` / `contentType`	`String`	`image/png` or `image/svg+xml`.
`bytes_1x` / `bytes1x`	`Vec<u8>`	The 32 px PNG (1x); empty for an SVG.

`SpaceAppIconRequest` record#

One window's app, for Space.app_icons.

Field	Type	Default	Description
`app_name` / `appName`	`String`		App name, as the window list reports it.
`app_id` / `appId`	`String`	`""`	App id (bundle id, `.desktop` id).
`pid`	`u32`	`0`	A process of the app (0 when unknown).

`SpaceDisplay` record#

One of a Space's displays (Space.displays).

Returned by Space.displays.

Field	Type	Description
`id`	`String`	Display id.
`name`	`String`	Name ("XVFB-0", "Built-in Retina Display").
`primary`	`bool`	The primary display.
`width_px` / `widthPx`	`u32`	Framebuffer width in physical pixels.
`height_px` / `heightPx`	`u32`	Framebuffer height in physical pixels.
`scale_factor` / `scaleFactor`	`f64`	Physical pixels per logical point.

`SpaceThumbnail` record#

A Space's latest thumbnail, from the cache every client on this machine shares (crate.native.spaces.Space.thumbnail).

Returned by Space.thumbnail.

Field	Type	Description
`image`	`Vec<u8>`	Encoded image (a small JPEG of the primary display).
`format`	`ImageFormat`	Encoding.
`width`	`u32`	Pixel width.
`height`	`u32`	Pixel height.
`captured_at_ms` / `capturedAtMs`	`u64`	When it was captured, Unix milliseconds.

`SpaceUsage` record#

Processor, memory and storage use (Space.usage). A size is the guest's own limit only when its *_limited flag says so (a VM's memory or disk, a container's cgroup memory limit).

Returned by Space.usage.

Field	Type	Default	Description
`cpu_count` / `cpuCount`	`u32`	`0`	Cores the guest sees (0 from a guest that does not report it).
`cpu_percent` / `cpuPercent`	`f64`	`0.0`	Busy now, 0 to 100.
`load_average_1m` / `loadAverage1m`	`f64`	`0.0`	1-minute load average.
`memory_used` / `memoryUsed`	`u64`		Memory in use, bytes.
`memory_total` / `memoryTotal`	`u64`		Memory size, bytes.
`memory_limited` / `memoryLimited`	`bool`		`memory_total` is the guest's limit.
`disk_used` / `diskUsed`	`u64`		Home filesystem bytes in use.
`disk_total` / `diskTotal`	`u64`		Home filesystem size, bytes.
`disk_limited` / `diskLimited`	`bool`		`disk_total` is the guest's own disk.

Teleport#

Teleport exports an app session from this machine and imports it on another. A consent callback sees the manifest first. Space.teleport and Space.teleport_manifest ask the Cua Spaces daemon, which runs teleport; an embedded runtime without Cua Spaces raises HostCapabilityMissing. To bring any app into a Space (install it, open files in it), see Teleport an app.

Teleport into a Space#

Methods of Space.

`Space.teleport`#

Teleports app's session into this Space. approver sees the manifest and returns the human's decision; None cancels (raises TeleportRefused). Sensitive items need an explicit acknowledgement.

Through a daemon, this may need two calls (see TeleportReceipt): the first returns status: "pending" with a request_id once the user's approval is filed with the Cua Keyvault; call again with that same request_id (approver is not consulted again -- the decision it already made was what the first call filed) until status: "moved". request_id is ignored for an embedded host, which always finishes in one call.

async def teleport(self, app: str, scope: Optional[str], approver: TeleportApprover, request_id: Optional[str] = None) -> TeleportReceipt

Parameter	Type	Default
`app`	`String`	required
`scope`	`Option<String>`	required
`approver`	`TeleportApprover`	required
`request_id`	`Option<String>`	`None`

Returns TeleportReceipt · Async · Raises CuaError (TeleportRefused)

`Space.teleport_manifest`#

What teleporting app (full or tabs) would move from this host.

async def teleport_manifest(self, app: str, scope: Optional[str]) -> TeleportManifest

Parameter	Type	Default
`app`	`String`	required
`scope`	`Option<String>`	required

Returns TeleportManifest · Async · Raises CuaError

`TeleportApprover`#

The consent gate of Space.teleport: shown the manifest, returns the human's decision, or None to cancel. Runs on a blocking worker thread; it may take as long as the human needs.

You implement TeleportApprover and pass it to the SDK (a callback interface): subclass it in Python, implement the interface in TypeScript, the TeleportApprover protocol in Swift, the interface in Kotlin and the trait in Rust.

Method	Description
`approve`	Decides.

`TeleportApprover.approve`#

Decides.

def approve(self, manifest: TeleportManifest) -> Optional[TeleportDecision]

Parameter	Type	Default
`manifest`	`TeleportManifest`	required

Returns Option<TeleportDecision>

`TeleportDecision` record#

A human's answer to a teleport manifest.

Returned by TeleportApprover.approve.

Field	Type	Default	Description
`include`	`Option<Vec<String>>`	`None`	Items to send (`None` = the provider's default-checked set, never everything). An empty list is refused as ambiguous.
`acknowledge_sensitive` / `acknowledgeSensitive`	`bool`	`false`	The human acknowledged the sensitive items in the selection.

`TeleportReceipt` record#

What a teleport moved, or how to retry a pending Keyvault approval.

Through a daemon (Host::Daemon), the underlying teleport_app tool is consent-gated: a first call never delivers, it only files the request and returns status: "pending" with a request_id; show the user the Keyvault approval step, then call Space.teleport again with that same request_id (TeleportRetry::request_id). A second "pending" means the user has not decided yet -- call again the same way. Only status: "moved" means the session actually landed. An embedded host (no separate daemon) always returns "moved" in one call: there is nothing to retry.

Returned by Space.teleport.

Field	Type	Description
`status`	`String`	`moved` or `pending`.
`request_id` / `requestId`	`Option<String>`	The Keyvault request to retry with, while pending.
`app`	`String`	App.
`space`	`String`	Space.
`method`	`String`	`import_session`.
`transferred_paths` / `transferredPaths`	`Vec<String>`	Paths sent.
`bundle_bytes` / `bundleBytes`	`u64`	Bundle bytes.
`bundle_sha256` / `bundleSha256`	`String`	Bundle SHA-256, verified by the Space.
`imported`	`Vec<String>`	Groups imported.
`skipped`	`Vec<String>`	Items skipped, with reasons.
`launched`	`bool`	The app was launched.

`TeleportItem` record#

One item a teleport would move.

Field	Type	Description
`relative_path` / `relativePath`	`String`	Bundle-relative path (what an approval names).
`label`	`String`	Label.
`estimated_bytes` / `estimatedBytes`	`u64`	Estimated bytes.
`is_sensitive` / `isSensitive`	`bool`	Credentials, cookies, tokens, transcripts.
`is_checked_by_default` / `isCheckedByDefault`	`bool`	In the default selection.
`count`	`Option<u64>`	Count of things it holds.
`count_noun` / `countNoun`	`Option<String>`	Noun for `count`.

`TeleportManifest` record#

Exactly what would leave this machine.

Returned by Space.teleport_manifest.

Field	Type	Description
`app`	`String`	Provider id (`firefox`, `chrome`, `claude-code`, ...).
`display_name` / `displayName`	`String`	Display name.
`scope`	`String`	`full` or `tabs`.
`items`	`Vec<TeleportItem>`	Items.
`total_estimated_bytes` / `totalEstimatedBytes`	`u64`	Provider total.
`notes`	`Vec<String>`	Provider caveats.

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.start_hotspot#

Space.stop_hotspot#

Space.supports#

Space.upload#

Space.write#

SpaceBashResult record#

SpaceWriteReport record#

SpaceTransferReport record#

SpaceSendFileOptions record#

SpaceSendFileReport record#

SpaceSentFile record#

SpaceWindow record#

SpaceToolInfo record#

SpaceToolResult record#

SpaceHotspotStatus record#

NetworkEvent record#

SharedBase record#

SiteLoginOptions record#

SiteLoginReport record#

SpaceCreatingElsewhere record#

SpaceWindowOrigin record#

EgressEnforcement enum#