Space list
The Space list (roster), the sidebar, a Space's detail and its remote windows.
The Space list (roster), the sidebar, a Space's detail and its remote windows.
These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.
The roster is the list of Spaces the app shows, from Spaces.list rows. app_roster_reduce applies an action; app_sidebar and app_space_detail derive the main window.
AppFactWarning record#| Field | Type | Default | Description |
|---|---|---|---|
symbol | String | SF Symbol (WARNING_SYMBOL). | |
help | String | Tooltip and accessibility label. |
app_rows_to_spaces#Registry rows (Spaces.list) as Spaces.
func appRowsToSpaces(rows: [AppSpaceRow], nowMs: Int64) -> [AppSpace]| Parameter | Type | Default |
|---|---|---|
rows | Vec<AppSpaceRow> | required |
now_ms | i64 | required |
Returns Vec<AppSpace>
app_status_line#The menu bar status line ("3 Spaces").
func appStatusLine(count: UInt32) -> String| Parameter | Type | Default |
|---|---|---|
count | u32 | required |
Returns String
app_this_machine_space#The "This machine" roster entry.
func appThisMachineSpace(status: AppHostSummaryInput?, nowMs: Int64) -> AppSpace| Parameter | Type | Default |
|---|---|---|
status | Option<AppHostSummaryInput> | required |
now_ms | i64 | required |
Returns AppSpace
AppHostSummaryInput record#Returned by app_host_summary_input.
| Field | Type | Default | Description |
|---|---|---|---|
configured | bool | Set up for access. | |
error | Option<String> | Needs attention. | |
service_running / serviceRunning | bool | The host service runs. | |
sharing | bool | Sharing is on. | |
clients | u32 | Connected clients. | |
mode | Option<String> | relay or direct. | |
online | Option<bool> | Relay presence. | |
paused_signed_out / pausedSignedOut | bool | Relay sharing is paused while signed out. |
app_agent_name#A coding agent's display name.
func appAgentName(agent: String) -> String| Parameter | Type | Default |
|---|---|---|
agent | String | required |
Returns String
AppAgentStatus enum#.running
.idle
.failed
.crashed
.unknown| Variant | Description |
|---|---|
Running | A turn is running. |
Idle | Waiting for a follow-up. |
Failed | Failed. |
Crashed | Crashed. |
Unknown | Could not be read. |
app_ambient_dots#The ambient status dots.
func appAmbientDots(spaces: [AppSpace]) -> AppAmbientDots| Parameter | Type | Default |
|---|---|---|
spaces | Vec<AppSpace> | required |
Returns AppAmbientDots
AppAmbientDots record#Returned by app_ambient_dots.
| Field | Type | Default | Description |
|---|---|---|---|
running | bool | Any Space running or starting. | |
approval | bool | Any Space waiting for approval. | |
suspended | bool | Any Space suspended. | |
agent_active / agentActive | bool | Any agent actively working. |
app_group_windows_by_app#A Space's remote windows grouped by app.
func appGroupWindowsByApp(windows: [AppRemoteWindow]) -> [AppRemoteWindowGroup]| Parameter | Type | Default |
|---|---|---|
windows | Vec<AppRemoteWindow> | required |
Returns Vec<AppRemoteWindowGroup>
AppOpenApp record#| Field | Type | Default | Description |
|---|---|---|---|
app_id / appId | String | App id. | |
app_name / appName | String | App name. | |
supported | bool | Supported. |
AppOpenWindow record#| Field | Type | Default | Description |
|---|---|---|---|
window_id / windowId | u32 | CoreGraphics window number. | |
app_id / appId | String | App id. | |
app_name / appName | String | App name. | |
window_title / windowTitle | String | Window title. | |
supported | bool | Teleport can bring the app up in a Space. | |
bundle_path / bundlePath | Option<String> | The owning app's bundle (or .desktop entry), when known. |
AppThumbnailScene enum#.macDesktop
.windowsDesktop
.linuxTerminal
.notes
.browser
.blank| Variant | Description |
|---|---|
MacDesktop | A macOS desktop. |
WindowsDesktop | A Windows desktop. |
LinuxTerminal | A Linux terminal. |
Notes | A notes app. |
Browser | A browser. |
Blank | Nothing. |
AppWindowMode enum#.ambient
.ambientTeleport
.switcher
.createFleet| Variant | Description |
|---|---|
Ambient | |
AmbientTeleport | Ambient, but grown taller so the drag teleport's "Teleport to Cua" box has room to hang below the notch. Same top-centre placement as Ambient. |
Switcher | |
CreateFleet |
AppNotice record#| Field | Type | Default | Description |
|---|---|---|---|
id | u32 | Sequence id (clear by id). | |
kind | AppNoticeKind | Kind. | |
text | String | Text. |
AppNoticeKind enum#.switch
.create| Variant | Description |
|---|---|
Switch | Switched Spaces. |
Create | Created (or creating) Spaces. |
AppNewSpaceOn record#| Field | Type | Default | Description |
|---|---|---|---|
label | String | The button's label. | |
on | String | The "Run on" entry it picks (host:<machine id>; the wizard's ChoosePlacement). |
app_hosted_rows#The Spaces one of your machines provides (machine_space_id is its
relay:<id>), as sidebar rows.
func appHostedRows(spaces: [AppSpace], machineSpaceId: String, selectedId: String) -> [AppSidebarRow]| Parameter | Type | Default |
|---|---|---|
spaces | Vec<AppSpace> | required |
machine_space_id | String | required |
selected_id | String | required |
Returns Vec<AppSidebarRow>
app_without_this_relay_machine#The roster without this machine's own relay entry (this_machine_id
is HostStatus.machine_id): it is "This machine", not one of "My
machines". Matched by id, never by name.
func appWithoutThisRelayMachine(spaces: [AppSpace], thisMachineId: String?) -> [AppSpace]| Parameter | Type | Default |
|---|---|---|
spaces | Vec<AppSpace> | required |
this_machine_id | Option<String> | required |
Returns Vec<AppSpace>
AppRemoteWindow record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | Stable key. | |
app_name / appName | String | App name. | |
title | String | Title. | |
visible | bool | Visible. | |
app_id / appId | String | App id. | |
target_epoch / targetEpoch | u64 | Window handle epoch. | |
width_px / widthPx | Option<u32> | Width, px. | |
height_px / heightPx | Option<u32> | Height, px. | |
pid | Option<u32> | The owning process (what the SDK's Space.app_icon looks a macOS app up by), when the window list reports one. |
AppRemoteWindowGroup record#Returned by app_group_windows_by_app.
| Field | Type | Default | Description |
|---|---|---|---|
app_id / appId | String | App id. | |
app_name / appName | String | App name. | |
windows | Vec<AppRemoteWindow> | Windows, arrival order. |
AppRosterState record#Returned by app_roster_initial, app_roster_reduce.
| Field | Type | Default | Description |
|---|---|---|---|
mode | AppWindowMode | The notch switcher's mode. | |
spaces | Vec<AppSpace> | Spaces, MRU order. | |
selected_id / selectedId | String | The selected Space id (empty when none). | |
focus_index / focusIndex | i32 | Keyboard focus: an index into spaces, or NEW_TILE_INDEX. | |
notice | Option<AppNotice> | The notice, if one shows. | |
notice_seq / noticeSeq | u32 | Last notice id. |
AppSidebarRow record#Returned by app_hosted_rows.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | Space id. | |
name | String | Name. | |
os_icon / osIcon | String | The Space's OS icon id (crate.notch.os_icon, the same mark the notch tiles use), before the name. | |
status | AppSpaceStatus | Status (the dot). | |
status_text / statusText | String | Status word (the dot's accessibility label). | |
detail | String | Tooltip. | |
dim | bool | Drawn at reduced opacity. | |
selected | bool | Selected. | |
progress | Option<u32> | While it is being created: overall progress in thousandths (a ring). | |
trailing | Option<String> | Short text after the name: the percentage while it is being created, the error when the create failed. | |
nested | bool | A Space one of your machines provides, drawn nested under that machine's row (the row before it). | |
power | Option<AppPowerButton> | The power button (next to Delete), for a Space whose provider can turn it off and on. | |
place | Option<String> | Where a Space in your cloud runs ("AWS · us-west-2"), secondary text after the name. |
AppSidebarSection record#| Field | Type | Default | Description |
|---|---|---|---|
title | String | "Cua Cloud", "This Mac", "Connected", "My machines". | |
rows | Vec<AppSidebarRow> | Rows. |
AppSidebarView record#Returned by app_sidebar.
| Field | Type | Default | Description |
|---|---|---|---|
this_machine / thisMachine | Option<AppSidebarRow> | The "This machine" row, when it matches the search. | |
sections | Vec<AppSidebarSection> | Location sections, in SECTION_ORDER. | |
selected_id / selectedId | Option<String> | The effective selection (falls back to the first Space). | |
empty_text / emptyText | Option<String> | "No matches" / "No Spaces yet" when nothing is listed. |
AppSpace record#Returned by app_creates_compose, app_rows_to_spaces, app_spaces_from_json, app_this_machine_space, app_with_this_machine, app_without_this_relay_machine.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | Sandbox ref (cloud:<name>, local:<name>, direct:<host:port>, ...). | |
name | String | Display name. | |
os | AppSpaceOs | Operating system. | |
status | AppSpaceStatus | Status. | |
detail | String | One short status detail. | |
last_used_at / lastUsedAt | i64 | Epoch ms of the last focus. | |
started_at / startedAt | Option<i64> | Epoch ms it was created. | |
scene | AppThumbnailScene | Placeholder scene. | |
fleet_id / fleetId | Option<String> | Group (cloud namespace or location word). | |
size | Option<String> | Fixture machine size. | |
region | Option<String> | Fixture region. | |
provider | Option<AppSpaceProvider> | Where it runs (cloud when omitted). | |
sdk | Option<AppSpaceSdkRef> | SDK facts, for Spaces from the live registry. | |
os_name / osName | Option<String> | The guest OS product or distribution ("Ubuntu", "macOS"), when the Space reported one: it picks the OS icon (crate.notch.os_icon). | |
os_pretty_name / osPrettyName | Option<String> | The guest's full OS string ("Ubuntu 24.04.3 LTS"), when the Space reported one. | |
image | Option<String> | The image it runs ("ghcr.io/trycua/linux:24.04"), when known. | |
image_digest / imageDigest | Option<String> | The digest of the variant that runs, when known. | |
progress | Option<AppSpaceProgress> | While it is being created: how far along, from the SDK's create progress (crate.spaces.creating). | |
kind | Option<AppSpaceKind> | Container or virtual machine, when known. | |
arch | Option<String> | The guest's CPU architecture (arm64, amd64), when known. | |
host | Option<String> | For a Space one of your machines provides: that machine's relay id (the sidebar nests it under the machine). | |
host_name / hostName | Option<String> | That machine's name, when known. | |
power | Option<AppSpacePower> | Whether and how it turns off and on (the SDK's power), with a power action in flight (crate.spaces.creating.compose). None: it cannot (a cloud Space, one added by address). | |
cloud | Option<String> | For a Space in your cloud: the provider word (aws, gcp, modal). | |
cloud_place / cloudPlace | Option<String> | Its account and region in words ("AWS · us-west-2"). | |
cloud_delete / cloudDelete | Option<String> | Where Delete permanently can delete it: here, host:<machine> (that machine created it) or elsewhere (another device did). |
AppSpaceAgentRun record#Returned by app_agent_rows.
| Field | Type | Default | Description |
|---|---|---|---|
run_id / runId | String | Run id. | |
agent | String | Harness id. | |
status | AppAgentStatus | Status. | |
reason | String | Why. | |
summary | String | Prompt summary. | |
created_at / createdAt | Option<i64> | Unix seconds. | |
phase | String | Finer phase. | |
turn | u32 | Turns. |
AppSpaceDetail record#Returned by app_space_detail, app_space_detail_for, app_space_detail_live, app_space_detail_with.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | Space id. | |
title | String | Title. | |
facts | Vec<AppFact> | Status, Image, System, Memory, Storage, Identifier (each when known). | |
is_host / isHost | bool | The host machine itself. | |
show_sections / showSections | bool | The Stream / Agents / Teleport sections show. | |
can_stream / canStream | bool | Streaming is possible (toolbar PiP and Stream). | |
preview_text / previewText | String | Placeholder over the preview until a frame arrives. | |
progress | Option<u32> | While it is being created: overall progress in thousandths (the preview's ring). | |
progress_text / progressText | Option<String> | Under the bar while it downloads: "4.2 of 22.1 GB · 85 MB/s · about 4 min". | |
delete_label / deleteLabel | String | "Remove" (added by address) or "Delete Space". | |
remove_only / removeOnly | bool | Removing only forgets it. | |
actions | Vec<AppDetailAction> | Toolbar buttons, in order (none for this machine). | |
confirm | AppDeleteConfirm | What Delete asks first. | |
sections | Vec<String> | The sections under the facts, in order (Stream, Agents, Teleport). | |
credit_notice / creditNotice | Option<AppCreditNotice> | A cloud Space refused for want of credit: one line and "Add credit" (the website billing page). | |
power_error / powerError | Option<String> | Why turning it off or on failed, shown inline under the preview. | |
access | Option<AppMachineAccessNotice> | Signed in, but this device is not enrolled: a machine reached through the relay is listed with its Connect greyed out under this line and its one action (detail_for). | |
desktop_note / desktopNote | Option<String> | One of your machines that does not share its desktop: the line shown in place of its desktop, Stream, Agents and Teleport (desktop_note). | |
new_space / newSpace | Option<AppNewSpaceOn> | With Self.desktop_note, when the machine provides Spaces: "New Space on <name>…", which opens New Space on it. |
AppSpaceProgress record#| Field | Type | Default | Description |
|---|---|---|---|
phase | String | The SDK's phase word (preparing, pulling, booting, ...). | |
permille | u32 | Overall progress in thousandths. | |
label | String | The phase in words ("Starting…", "Downloading image…"), or "Failed". | |
error | Option<String> | Why the create failed. | |
credit_url / creditUrl | Option<String> | It failed because the account is out of Cua Cloud credit: the website billing page "Add credit" opens. | |
transfer | Option<String> | While it downloads: "4.2 of 22.1 GB · 85 MB/s · about 4 min" (crate.spaces.creating.transfer_text). | |
cancellable | bool | Cancel can stop it now. | |
cancelling | bool | Cancel was pressed and the create is being cleaned up. |
AppSpaceRow record#Returned by app_space_rows_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | Sandbox ref. | |
name | String | Name spacesd reported. | |
provider | String | Location word. | |
spacesd_version / spacesdVersion | String | spacesd version. | |
features | Vec<String> | spacesd features. | |
added_at / addedAt | Option<String> | RFC 3339 time it was added. | |
os | Option<AppSpaceOs> | Operating system. | |
os_name / osName | Option<String> | OS product or distribution spacesd reported ("Ubuntu"). | |
os_pretty_name / osPrettyName | Option<String> | The guest's full OS string ("Ubuntu 24.04.3 LTS"), when the Space reported one. | |
image | Option<String> | The image it runs ("ghcr.io/trycua/linux:24.04"), when known. | |
image_digest / imageDigest | Option<String> | The digest of the variant that runs, when known. | |
kind | Option<AppSpaceKind> | Container or virtual machine, when known. | |
arch | Option<String> | The guest's CPU architecture, when known (any spelling: arm64, aarch64, amd64, x86_64). | |
reachable | bool | Answered the last connect. | |
error | Option<String> | Why not. | |
host | Option<String> | For a Space one of your machines provides: that machine's relay id. | |
host_name / hostName | Option<String> | That machine's name, when known. | |
power | Option<String> | How it turns off and on (suspend, stop); absent when it cannot. | |
power_state / powerState | Option<String> | running, suspended or stopped as the SDK recorded it; absent when unknown. | |
cloud | Option<String> | For a Space in your cloud: the provider word (aws, gcp, modal). | |
cloud_place / cloudPlace | Option<String> | Its account and region in words ("AWS · us-west-2"). | |
cloud_delete / cloudDelete | Option<String> | Where Delete permanently can delete it: here, host:<machine> (that machine created it) or elsewhere (another device did). |
AppSpaceSdkRef record#| Field | Type | Default | Description |
|---|---|---|---|
features | Vec<String> | spacesd feature names. | |
spacesd_version / spacesdVersion | String | spacesd version at the last handshake. | |
reachable | bool | Answered the last bounded connect. | |
error | Option<String> | Why not. |
AppRosterAction enum#.expand
.collapse
.openCreate
.cancelCreate
.focus(index: Int32)
.focusMove(delta: Int32)
.select(id: String, now: Int64)
.clearNotice(id: UInt32)
.notify(text: String, kind: AppNoticeKind?)
.syncSpaces(spaces: [AppSpace])| Variant | Description |
|---|---|
Expand | Open the switcher. |
Collapse | Back to ambient. |
OpenCreate | Open the create panel. |
CancelCreate | Close it. |
Focus | Focus a tile. Fields: index: i32 |
FocusMove | Move focus by one, wrapping through the New tile. Fields: delta: i32 |
Select | Select a Space (touches its MRU time). Fields: id: String, now: i64 |
ClearNotice | Clear the notice with this id. Fields: id: u32 |
Notify | Show a notice. Fields: text: String, kind: Option<AppNoticeKind> |
SyncSpaces | Replace the list with a registry refresh. Fields: spaces: Vec<AppSpace> |
AppSpaceKind enum#.container
.vm| Variant | Description |
|---|---|
Container | A container. |
Vm | A virtual machine. |
AppSpaceOs enum#.macos
.windows
.linux
.unknown| Variant | Description |
|---|---|
Macos | macOS. |
Windows | Windows. |
Linux | Linux. |
Unknown | The host has not reported a recognized operating system. |
AppSpaceProvider enum#.cloud
.local
.direct
.relay| Variant | Description |
|---|---|
Cloud | Cua Cloud. |
Local | This Mac. |
Direct | A machine added by address. |
Relay | A machine of the signed-in account through the relay. |
AppSpaceStatus enum#.local
.running
.approval
.suspended
.provisioning
.deleting| Variant | Description |
|---|---|
Local | The host machine itself. |
Running | Reachable, session active. |
Approval | An agent waits for approval. |
Suspended | Unreachable or suspended. |
Provisioning | Being created. |
Deleting | Being deleted (the user confirmed; the SDK is removing it). |
app_roster_initial#The Space list's first state.
func appRosterInitial(spaces: [AppSpace]) -> AppRosterState| Parameter | Type | Default |
|---|---|---|
spaces | Vec<AppSpace> | required |
Returns AppRosterState
app_roster_reduce#Advances the Space list.
func appRosterReduce(state: AppRosterState, action: AppRosterAction) -> AppRosterState| Parameter | Type | Default |
|---|---|---|
state | AppRosterState | required |
action | AppRosterAction | required |
Returns AppRosterState
app_sidebar#The main window's sidebar.
func appSidebar(spaces: [AppSpace], query: String, selectedId: String) -> AppSidebarView| Parameter | Type | Default |
|---|---|---|
spaces | Vec<AppSpace> | required |
query | String | required |
selected_id | String | required |
Returns AppSidebarView
app_space_accepts_drop#Whether a Space takes a teleport drop (the notch tiles' and the Space rows' rule).
func appSpaceAcceptsDrop(space: AppSpace) -> Bool| Parameter | Type | Default |
|---|---|---|
space | AppSpace | required |
Returns bool
app_space_detail#A Space's detail.
func appSpaceDetail(space: AppSpace) -> AppSpaceDetail| Parameter | Type | Default |
|---|---|---|
space | AppSpace | required |
Returns AppSpaceDetail
app_space_detail_for#app_space_detail_with as this device sees it: access (from
app_machine_access_notice) greys out Connect on every Space reached
through the relay while this device is not enrolled; one of your
machines that does not share its desktop shows its note in place of the
desktop, Stream, Agents and Teleport.
func appSpaceDetailFor(space: AppSpace, usage: AppSpaceUsage?, hostArch: String?, experiments: AppExperiments, access: AppMachineAccessNotice?) -> AppSpaceDetail| Parameter | Type | Default |
|---|---|---|
space | AppSpace | required |
usage | Option<AppSpaceUsage> | required |
host_arch | Option<String> | required |
experiments | AppExperiments | required |
access | Option<AppMachineAccessNotice> | required |
Returns AppSpaceDetail
app_space_detail_with#app_space_detail_live without what Settings, Experiments hides (the
Share button while Sharing is off).
func appSpaceDetailWith(space: AppSpace, usage: AppSpaceUsage?, hostArch: String?, experiments: AppExperiments) -> AppSpaceDetail| Parameter | Type | Default |
|---|---|---|
space | AppSpace | required |
usage | Option<AppSpaceUsage> | required |
host_arch | Option<String> | required |
experiments | AppExperiments | required |
Returns AppSpaceDetail
app_space_rows_from_json#Registry rows from JSON (fixtures, parity flows).
func appSpaceRowsFromJson(json: String) throws -> [AppSpaceRow]| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns Vec<AppSpaceRow> · Raises CuaError
app_spaces_from_json#Spaces from the webview's JSON shape (fixtures, parity flows).
func appSpacesFromJson(json: String) throws -> [AppSpace]| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns Vec<AppSpace> · Raises CuaError