This machine

The This machine roster entry, its page and the host setup form.

Cua Spaces app export

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.

app_with_this_machine puts This machine first in the roster. app_host_panel derives its page from app_host_state; app_host_form_reduce and app_host_form_view drive the host setup form, whose request goes to app_host_setup (Swift: host.setupRequest(...)).

`app_with_this_machine`#

Adds the "This machine" entry to a roster, first.

func appWithThisMachine(spaces: [AppSpace], status: AppHostSummaryInput?, nowMs: Int64) -> [AppSpace]

Parameter	Type	Default
`spaces`	`Vec<AppSpace>`	required
`status`	`Option<AppHostSummaryInput>`	required
`now_ms`	`i64`	required

Returns Vec<AppSpace>

`AppPermissionRow` record#

Returned by app_host_permission_rows.

Field	Type	Description
`id`	`String`	Id.
`title`	`String`	"Screen Recording".
`help`	`String`	Tooltip (what to turn on).
`settings_url` / `settingsUrl`	`Option<String>`	The pane (only a `x-apple.systempreferences:` URL is opened).

`AppHostAccess` record#

Field	Type	Description
`at_ms` / `atMs`	`i64`	Epoch ms.
`via`	`String`	How the caller authenticated: `relay`, `viewer` or `token`.
`who`	`String`	Who (a relay-verified account, a viewer, or the token holder).
`what`	`String`	What they used (a service name such as `ProcessService`, or `MCP`).

`AppHostAccessRow` record#

Field	Type	Default	Description
`text`	`String`		"Ada · Files".
`at_ms` / `atMs`	`i64`		Epoch ms (each shell shows it relative, natively).

`AppHostAction` record#

Field	Type	Description
`id`	`AppHostActionId`	What it does.
`label`	`String`	Label.
`destructive`	`bool`	Drawn as destructive.
`confirm`	`Option<AppHostConfirm>`	Ask this first; the action runs only when the user confirms.

`AppHostClient` record#

Field	Type	Description
`id`	`String`	Account id.
`email`	`Option<String>`	Email.
`name`	`Option<String>`	Display name.
`streams`	`Option<u32>`	Open streams.

`AppHostConfirm` record#

Field	Type	Description
`title`	`String`	The question.
`message`	`String`	What happens.
`confirm_label` / `confirmLabel`	`String`	The confirming button.
`cancel_label` / `cancelLabel`	`String`	The other button.

`AppHostFormChoice` record#

Field	Type	Default	Description
`id`	`String`		`desktop` or `spare`.
`label`	`String`		Label.

`AppHostFormField` record#

Field	Type	Description
`id`	`String`	`name`, `allow`, `direct`, `listen`, `relay`.
`label`	`String`	Label.
`placeholder`	`Option<String>`	Placeholder (text fields).
`value`	`String`	Text.
`toggle`	`bool`	The switch (`direct` only).
`on`	`bool`	On (`direct` only).
`invalid`	`bool`	Drawn as invalid.
`advanced`	`bool`	Under Advanced.
`choices`	`Vec<AppHostFormChoice>`	A choice of one (`profile` only): `value` is the chosen id.

`AppHostFormState` record#

Returned by app_host_form_initial, app_host_form_reduce.

Field	Type	Description
`name`	`String`	Display name.
`allow`	`String`	"Also allow" (relay).
`advanced`	`bool`	Advanced is open.
`direct`	`bool`	Direct instead of the relay (Advanced).
`listen`	`String`	Direct listen address.
`relay_url` / `relayUrl`	`String`	Relay URL (Advanced).
`busy`	`bool`	Setup is running.
`error`	`Option<String>`	The last failure.
`spare`	`bool`	A spare machine: do not share its desktop, provide Spaces (relay only).

`AppHostFormView` record#

Returned by app_host_form_view.

Field	Type	Description
`title`	`String`	"Set up this machine".
`lede`	`String`	One line: what setting up does.
`fields`	`Vec<AppHostFormField>`	Visible fields in order (Advanced ones only while it is open).
`advanced_label` / `advancedLabel`	`String`	"Advanced".
`advanced_open` / `advancedOpen`	`bool`	Advanced is open.
`back_label` / `backLabel`	`String`	"Back".
`submit_label` / `submitLabel`	`String`	"Set up for access" or "Setting up…".
`can_submit` / `canSubmit`	`bool`	The submit button is enabled.
`busy`	`bool`	Setup is running.
`error`	`Option<String>`	The last failure, one line.
`request`	`Option<AppHostSetupRequest>`	What host setup receives (validated), when it can submit.

`AppHostLimit` record#

Field	Type	Description
`resource`	`String`	`spaces` (every Space it provides) or `macos_vms` (macOS VMs on that Mac).
`used`	`u32`	In use now.
`limit`	`u32`	The limit (0: none).
`reason`	`String`	Why the limit exists, for people ("Apple's macOS license allows two macOS VMs per Mac").

`AppHostPanelView` record#

Returned by app_host_panel.

Field	Type	Description
`title`	`String`	"This machine".
`summary`	`String`	One line: how it is shared, or that it is not.
`configured`	`bool`	Set up for access.
`facts`	`Vec<AppFact>`	Name, Access, Service.
`clients_title` / `clientsTitle`	`Option<String>`	"Connected now" (configured only).
`clients`	`Vec<String>`	One line per client.
`clients_empty` / `clientsEmpty`	`Option<String>`	"Nobody" when nobody is connected.
`recent_title` / `recentTitle`	`Option<String>`	"Recent access" (configured, when the log has any).
`recent`	`Vec<AppHostAccessRow>`	Who reached this machine recently, newest first.
`access_warning` / `accessWarning`	`Option<String>`	Set when the access log does not verify.
`toggles`	`Vec<AppHostToggle>`	The two settings (configured only).
`limits`	`Option<String>`	The limits, one line ("Up to 4 Spaces \u{b7} 2 macOS VMs"), while providing Spaces.
`provided_title` / `providedTitle`	`Option<String>`	"Spaces for your devices", while providing Spaces.
`provided`	`Vec<AppHostAccessRow>`	One row per Space this machine provides.
`provided_empty` / `providedEmpty`	`Option<String>`	"None yet" when it provides none.
`activity_title` / `activityTitle`	`Option<String>`	"Spaces activity" (when the audit has any).
`activity`	`Vec<AppHostAccessRow>`	Remote creates, deletes and refusals, newest first.
`activity_warning` / `activityWarning`	`Option<String>`	Set when the Spaces audit does not verify.
`permissions_title` / `permissionsTitle`	`Option<String>`	Heading over the permission rows, when any is left to grant.
`permissions`	`Vec<AppPermissionRow>`	Panes still to grant.
`open_settings_label` / `openSettingsLabel`	`String`	The permission rows' button.
`actions`	`Vec<AppHostAction>`	Buttons, primary first.

`AppHostPermissionInput` record#

Field	Type	Description
`id`	`String`	`screen-recording`, `accessibility`.
`title`	`String`	"Screen Recording".
`settings_url` / `settingsUrl`	`Option<String>`	The pane to open.
`instructions`	`Option<String>`	What to turn on there.
`granted`	`bool`	Already granted.

`AppHostProvidedSpace` record#

Field	Type	Description
`relay_machine` / `relayMachine`	`String`	The relay machine it is reached as.
`local_space` / `localSpace`	`String`	The Space on this machine (`local:<name>`).
`name`	`String`	Display name.
`image`	`String`	The image.
`os`	`String`	`linux`, `macos`.
`kind`	`String`	`container` or `vm`.
`created_by` / `createdBy`	`String`	Who created it.
`created_at_ms` / `createdAtMs`	`i64`	Epoch ms.

`AppHostSettingChange` record#

Returned by app_host_setting_change.

Field	Type	Default	Description
`share_desktop` / `shareDesktop`	`Option<bool>`		Share this desktop.
`provide_spaces` / `provideSpaces`	`Option<bool>`		Provide Spaces.

`AppHostSetupRequest` record#

Returned by app_host_validate_setup.

Field	Type	Description
`mode`	`String`	`relay` (default) or `direct`.
`relay_url` / `relayUrl`	`Option<String>`	Relay URL; `None` uses the configured default (https://relay.cua.ai).
`direct`	`Option<String>`	Direct `ip:port` (Advanced).
`name`	`Option<String>`	Display name (default: the host name).
`allow`	`Option<Vec<String>>`	Accounts (ids or emails) allowed besides the owner.
`profile`	`Option<String>`	What the machine is for: `desktop` (share this desktop; the default) or `spare` (only run Spaces for your other devices).
`share_desktop` / `shareDesktop`	`Option<bool>`	Share this machine's own desktop (overrides the profile).
`provide_spaces` / `provideSpaces`	`Option<bool>`	Create Spaces for your other devices (overrides the profile).

`AppHostSpacesAudit` record#

Field	Type	Description
`at_ms` / `atMs`	`i64`	Epoch ms.
`action`	`String`	`create`, `delete`, `refused`, `failed`, `config`.
`who`	`String`	Who (an account, or `local`).
`space`	`String`	The relay machine or Space.
`detail`	`String`	Detail.

`AppHostState` record#

Returned by app_host_state, app_host_state_from_json.

Field	Type	Description
`configured`	`bool`	Set up for access.
`mode`	`Option<String>`	`relay` or `direct`.
`relay_url` / `relayUrl`	`Option<String>`	Relay URL.
`direct_url` / `directUrl`	`Option<String>`	Direct URL.
`name`	`Option<String>`	Display name.
`sharing`	`bool`	Accepting clients.
`service_installed` / `serviceInstalled`	`bool`	Service installed.
`service_running` / `serviceRunning`	`bool`	Service running.
`service_kind` / `serviceKind`	`String`	`launchd`, `systemd`, `windows-task`, `process`.
`online`	`Option<bool>`	Online at the relay.
`clients`	`Vec<AppHostClient>`	Connected now.
`permissions`	`Vec<AppHostPermissionInput>`	Panes to grant.
`error`	`Option<String>`	Needs attention.
`recent_access` / `recentAccess`	`Vec<AppHostAccess>`	Who reached this machine recently, newest first.
`access_log_error` / `accessLogError`	`Option<String>`	Set when the access log does not verify (edited or truncated).
`share_desktop` / `shareDesktop`	`bool`	This machine's own desktop is a Space.
`provide_spaces` / `provideSpaces`	`bool`	This machine creates Spaces for your other devices.
`max_spaces` / `maxSpaces`	`u32`	Provided Spaces at once (0: no limit).
`max_macos_vms` / `maxMacosVms`	`u32`	macOS VMs at once (at most two; 0 off a Mac).
`provided_spaces` / `providedSpaces`	`Vec<AppHostProvidedSpace>`	The Spaces this machine provides now.
`spaces_audit` / `spacesAudit`	`Vec<AppHostSpacesAudit>`	Remote creates, deletes and refusals, and settings changes, newest first.
`spaces_audit_error` / `spacesAuditError`	`Option<String>`	Set when the Spaces audit does not verify.

`AppHostToggle` record#

Field	Type	Description
`id`	`String`	`desktop` or `spaces`.
`label`	`String`	Label.
`help`	`String`	One line under it.
`on`	`bool`	On now.
`enabled`	`bool`	Can be flipped (the last setting on cannot be turned off; Spaces need the relay).
`action`	`AppHostActionId`	What flipping it runs.

`AppHostActionId` enum#

.setUp
.stopSharing
.resumeSharing
.remove
.shareDesktop
.hideDesktop
.provideSpaces
.stopProvidingSpaces

Variant	Description
`SetUp`	Open the host setup form.
`StopSharing`	Cut clients and refuse new ones.
`ResumeSharing`	Accept clients again.
`Remove`	Unregister and uninstall the service.
`ShareDesktop`	Share this machine's own desktop.
`HideDesktop`	Stop sharing this machine's own desktop (Spaces keep running).
`ProvideSpaces`	Create Spaces for your other devices.
`StopProvidingSpaces`	Stop creating Spaces for your other devices.

`AppHostFormAction` enum#

.setName(name: String)
.setAllow(allow: String)
.toggleAdvanced
.setDirect(on: Bool)
.setListen(listen: String)
.setRelayUrl(url: String)
.setProfile(profile: String)
.submit
.failed(error: String)

Variant	Description
`SetName`	Name typed. Fields: `name: String`
`SetAllow`	"Also allow" typed. Fields: `allow: String`
`ToggleAdvanced`	Advanced opened or closed.
`SetDirect`	"Direct connection" switched. Fields: `on: bool`
`SetListen`	Listen address typed. Fields: `listen: String`
`SetRelayUrl`	Relay URL typed. Fields: `url: String`
`SetProfile`	What the machine is for: `desktop` or `spare`. Fields: `profile: String`
`Submit`	"Set up for access" pressed (ignored unless it can submit).
`Failed`	Setup failed. Fields: `error: String`

`app_host_arch`#

This machine's CPU architecture as the Spaces apps pass it to the core (arm64, amd64).

func appHostArch() -> String

Returns String

`app_host_form_action_from_json`#

A host setup form action from JSON (parity flows).

func appHostFormActionFromJson(json: String) throws -> AppHostFormAction

Parameter	Type	Default
`json`	`String`	required

Returns AppHostFormAction · Raises CuaError

`app_host_form_initial`#

The host setup form's first state.

func appHostFormInitial() -> AppHostFormState

Returns AppHostFormState

`app_host_form_reduce`#

Advances the host setup form.

func appHostFormReduce(state: AppHostFormState, action: AppHostFormAction) -> AppHostFormState

Parameter	Type	Default
`state`	`AppHostFormState`	required
`action`	`AppHostFormAction`	required

Returns AppHostFormState

`app_host_form_view`#

The host setup form as drawn (identity: the signed-in account).

func appHostFormView(state: AppHostFormState, identity: String?) -> AppHostFormView

Parameter	Type	Default
`state`	`AppHostFormState`	required
`identity`	`Option<String>`	required

Returns AppHostFormView

`app_host_looks_like_listen`#

Whether a direct-mode address is ip:port or host:port.

func appHostLooksLikeListen(value: String) -> Bool

Parameter	Type	Default
`value`	`String`	required

Returns bool

`app_host_panel`#

The "This machine" page (None while the host status loads).

func appHostPanel(state: AppHostState?) -> AppHostPanelView

Parameter	Type	Default
`state`	`Option<AppHostState>`	required

Returns AppHostPanelView

`app_host_parse_allow_list`#

Comma or space separated accounts, as the host setup form's "Also allow".

func appHostParseAllowList(value: String) -> [String]

Parameter	Type	Default
`value`	`String`	required

Returns Vec<String>

`app_host_permission_rows`#

Permission panes still to grant, as rows.

func appHostPermissionRows(permissions: [AppHostPermissionInput]) -> [AppPermissionRow]

Parameter	Type	Default
`permissions`	`Vec<AppHostPermissionInput>`	required

Returns Vec<AppPermissionRow>

`app_host_setting_change`#

The settings change a host toggle action runs (None for the other actions): pass it to Host.configure.

func appHostSettingChange(id: AppHostActionId) -> AppHostSettingChange?

Parameter	Type	Default
`id`	`AppHostActionId`	required

Returns Option<AppHostSettingChange>

`app_host_setup`#

Host setup from the first-run form, as both Spaces apps send it: validated by the app core (app_host_validate_setup), then the SDK's Host.setup (the Swift app calls it as host.setupRequest(...)).

func appHostSetup(host: Host, request: AppHostSetupRequest, accountToken: String?) async throws -> HostStatus

Parameter	Type	Default
`host`	`Host`	required
`request`	`AppHostSetupRequest`	required
`account_token`	`Option<String>`	required

Returns HostStatus · Async · Raises CuaError

`app_host_state`#

The cua SDK's host status as the app core reads it.

func appHostState(status: HostStatus) -> AppHostState

Parameter	Type	Default
`status`	`HostStatus`	required

Returns AppHostState

`app_host_state_from_json`#

A host state from JSON (fixtures, parity flows).

func appHostStateFromJson(json: String) throws -> AppHostState

Parameter	Type	Default
`json`	`String`	required

Returns AppHostState · Raises CuaError

`app_host_summary_input`#

What the sidebar row's summary reads from a host state.

func appHostSummaryInput(state: AppHostState) -> AppHostSummaryInput

Parameter	Type	Default
`state`	`AppHostState`	required

Returns AppHostSummaryInput

`app_host_validate_setup`#

Normalises and checks a host setup request (the Tauri app's host_setup runs the same check before any service is touched).

func appHostValidateSetup(request: AppHostSetupRequest) throws -> AppHostSetupRequest

Parameter	Type	Default
`request`	`AppHostSetupRequest`	required

Returns AppHostSetupRequest · Raises CuaError

This machine

app_with_this_machine#

AppPermissionRow record#

AppHostAccess record#

AppHostAccessRow record#

AppHostAction record#

AppHostClient record#

AppHostConfirm record#

AppHostFormChoice record#

AppHostFormField record#

AppHostFormState record#

AppHostFormView record#

AppHostLimit record#

AppHostPanelView record#

AppHostPermissionInput record#

AppHostProvidedSpace record#

AppHostSettingChange record#

AppHostSetupRequest record#

AppHostSpacesAudit record#

AppHostState record#

AppHostToggle record#

AppHostActionId enum#

AppHostFormAction enum#

app_host_arch#

app_host_form_action_from_json#

app_host_form_initial#

app_host_form_reduce#

app_host_form_view#

app_host_looks_like_listen#

app_host_panel#

app_host_parse_allow_list#

app_host_permission_rows#

app_host_setting_change#

app_host_setup#

app_host_state#

app_host_state_from_json#

app_host_summary_input#

app_host_validate_setup#

app_with_this_machine#

AppPermissionRow record#

AppHostAccess record#

AppHostAccessRow record#

AppHostAction record#

AppHostClient record#

AppHostConfirm record#

AppHostFormChoice record#

AppHostFormField record#

AppHostFormState record#

AppHostFormView record#

AppHostLimit record#

AppHostPanelView record#

AppHostPermissionInput record#

AppHostProvidedSpace record#

AppHostSettingChange record#

AppHostSetupRequest record#

AppHostSpacesAudit record#

AppHostState record#

AppHostToggle record#

AppHostActionId enum#

AppHostFormAction enum#

app_host_arch#

app_host_form_action_from_json#

app_host_form_initial#

app_host_form_reduce#

app_host_form_view#

app_host_looks_like_listen#

app_host_panel#

app_host_parse_allow_list#

app_host_permission_rows#

app_host_setting_change#

app_host_setup#

app_host_state#

app_host_state_from_json#

app_host_summary_input#

app_host_validate_setup#

`app_with_this_machine`#

`AppPermissionRow` record#

`AppHostAccess` record#

`AppHostAccessRow` record#

`AppHostAction` record#

`AppHostClient` record#

`AppHostConfirm` record#

`AppHostFormChoice` record#

`AppHostFormField` record#

`AppHostFormState` record#

`AppHostFormView` record#

`AppHostLimit` record#

`AppHostPanelView` record#

`AppHostPermissionInput` record#

`AppHostProvidedSpace` record#

`AppHostSettingChange` record#

`AppHostSetupRequest` record#

`AppHostSpacesAudit` record#

`AppHostState` record#

`AppHostToggle` record#

`AppHostActionId` enum#

`AppHostFormAction` enum#

`app_host_arch`#

`app_host_form_action_from_json`#

`app_host_form_initial`#

`app_host_form_reduce`#

`app_host_form_view`#

`app_host_looks_like_listen`#

`app_host_panel`#

`app_host_parse_allow_list`#

`app_host_permission_rows`#

`app_host_setting_change`#

`app_host_setup`#

`app_host_state`#

`app_host_state_from_json`#

`app_host_summary_input`#

`app_host_validate_setup`#

`app_with_this_machine`#

`AppPermissionRow` record#

`AppHostAccess` record#

`AppHostAccessRow` record#

`AppHostAction` record#

`AppHostClient` record#

`AppHostConfirm` record#

`AppHostFormChoice` record#

`AppHostFormField` record#

`AppHostFormState` record#

`AppHostFormView` record#

`AppHostLimit` record#

`AppHostPanelView` record#

`AppHostPermissionInput` record#

`AppHostProvidedSpace` record#

`AppHostSettingChange` record#

`AppHostSetupRequest` record#

`AppHostSpacesAudit` record#

`AppHostState` record#

`AppHostToggle` record#

`AppHostActionId` enum#

`AppHostFormAction` enum#

`app_host_arch`#

`app_host_form_action_from_json`#

`app_host_form_initial`#

`app_host_form_reduce`#

`app_host_form_view`#

`app_host_looks_like_listen`#

`app_host_panel`#

`app_host_parse_allow_list`#

`app_host_permission_rows`#

`app_host_setting_change`#

`app_host_setup`#

`app_host_state`#

`app_host_state_from_json`#

`app_host_summary_input`#

`app_host_validate_setup`#