Host and relay

Unattended host setup and the cua-relay directory client.

Set this machine up for unattended access, and reach account machines through the relay.

`Host`#

This machine as an unattended-access host.

Method	Description
`new`	Host state under `cua_home` (default `$CUA_HOME` or `~/.cua`).
`configure`	Changes what this machine shares: its own desktop, and whether it creates Spaces for your other devices (and their limits).
`remove`	Unregister, uninstall the service and delete the host state.
`setup`	Installs and starts the host service (relay mode needs `account_token`).
`start_sharing`	Start sharing again.
`status`	Current state.
`stop_sharing`	Stop sharing (cut clients, refuse new ones).

`Host.new`#

Host state under cua_home (default $CUA_HOME or ~/.cua).

Host(cua_home: Optional[str])

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

Returns Host

`Host.configure`#

Changes what this machine shares: its own desktop, and whether it creates Spaces for your other devices (and their limits). Turning the desktop on or off restarts the host service.

async def configure(self, change: HostSettingsChange) -> HostStatus

Parameter	Type	Default
`change`	`HostSettingsChange`	required

Returns HostStatus · Async · Raises CuaError

`Host.remove`#

Unregister, uninstall the service and delete the host state.

async def remove(self) -> None

Async · Raises CuaError

`Host.setup`#

Installs and starts the host service (relay mode needs account_token).

async def setup(self, options: HostSetupOptions, account_token: Optional[str]) -> HostStatus

Parameter	Type	Default
`options`	`HostSetupOptions`	required
`account_token`	`Option<String>`	required

Returns HostStatus · Async · Raises CuaError

`Host.start_sharing`#

Start sharing again.

async def start_sharing(self) -> HostStatus

Returns HostStatus · Async · Raises CuaError

`Host.status`#

Current state.

async def status(self) -> HostStatus

Returns HostStatus · Async · Raises CuaError

`Host.stop_sharing`#

Stop sharing (cut clients, refuse new ones).

async def stop_sharing(self) -> HostStatus

Returns HostStatus · Async · Raises CuaError

`Relay`#

The signed-in account's view of a cua-relay.

Method	Description
`new`	A relay (`None` = `CUA_RELAY_URL`, else `https://relay.cua.ai`) seen as the account behind `account_token` (a cua.ai access token).
`connect`	Connects to a machine's spacesd through `<relay>/m/<id>`, with the account token as bearer (the relay swaps it for its signed identity).
`machine`	One machine.
`machines`	Machines the account owns or that are shared with it.
`start_sharing`	Accepts clients again.
`stop_sharing`	Cuts every client of a machine the account owns and refuses new ones.

Accessor	Returns	Description
`url()`	`String`	Normalized relay base URL.

`Relay.new`#

A relay (None = CUA_RELAY_URL, else https://relay.cua.ai) seen as the account behind account_token (a cua.ai access token).

Relay(relay_url: Optional[str], account_token: str)

Parameter	Type	Default
`relay_url`	`Option<String>`	required
`account_token`	`String`	required

Returns Relay · Raises CuaError

`Relay.connect`#

Connects to a machine's spacesd through <relay>/m/<id>, with the account token as bearer (the relay swaps it for its signed identity).

async def connect(self, machine_id: str) -> SpacesdClient

Parameter	Type	Default
`machine_id`	`String`	required

Returns SpacesdClient · Async · Raises CuaError

`Relay.machine`#

One machine.

async def machine(self, machine_id: str) -> RelayMachine

Parameter	Type	Default
`machine_id`	`String`	required

Returns RelayMachine · Async · Raises CuaError

`Relay.machines`#

Machines the account owns or that are shared with it.

async def machines(self) -> List[RelayMachine]

Returns Vec<RelayMachine> · Async · Raises CuaError

`Relay.start_sharing`#

Accepts clients again.

async def start_sharing(self, machine_id: str) -> RelayMachine

Parameter	Type	Default
`machine_id`	`String`	required

Returns RelayMachine · Async · Raises CuaError

`Relay.stop_sharing`#

Cuts every client of a machine the account owns and refuses new ones.

async def stop_sharing(self, machine_id: str) -> RelayMachine

Parameter	Type	Default
`machine_id`	`String`	required

Returns RelayMachine · Async · Raises CuaError

`HostAccessRecord` record#

One access to this machine.

Field	Type	Description
`at_ms` / `atMs`	`i64`	Epoch ms.
`via`	`String`	`relay`, `viewer` or `token`.
`who`	`String`	Who.
`what`	`String`	What they used (a service name, or `MCP`).

`HostPermission` record#

A macOS privacy pane the user must grant.

Field	Type	Description
`id`	`String`	`screen-recording` or `accessibility`.
`title`	`String`	Title.
`settings_url` / `settingsUrl`	`String`	`x-apple.systempreferences:` URL.
`instructions`	`String`	Instructions.

`HostProvidedSpace` record#

A Space this machine provides to one of your devices.

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

`HostSettingsChange` record#

A change to this machine's Spaces settings (None keeps a value).

Field	Type	Default	Description
`share_desktop` / `shareDesktop`	`Option<bool>`	`None`	Share this desktop.
`provide_spaces` / `provideSpaces`	`Option<bool>`	`None`	Provide Spaces.
`max_spaces` / `maxSpaces`	`Option<u32>`	`None`	Provided Spaces at once (0: no limit).
`max_macos_vms` / `maxMacosVms`	`Option<u32>`	`None`	macOS VMs at once (0 to 2, Apple's license).

`HostSetupOptions` record#

cua host setup options.

Field	Type	Default	Description
`mode`	`Option<String>`		`relay` (default) or `direct`.
`relay_url` / `relayUrl`	`Option<String>`		Relay URL (relay mode; default `CUA_RELAY_URL` / `https://relay.cua.ai`).
`direct`	`Option<String>`		`ip:port` (direct mode; default `0.0.0.0:3211`).
`name`	`Option<String>`		Display name (default: host name).
`allow`	`Vec<String>`		Accounts (ids or emails) allowed besides the owner.
`driver_bin` / `driverBin`	`Option<String>`		Driver binary (else `CUA_SPACESD_BIN`, bundled, or download).
`runner`	`Option<String>`		`auto`, `systemd`, `launchd`, `windows-task` or `process`.
`profile`	`Option<String>`	`None`	`desktop` (share this desktop; the default) or `spare` (do not share the desktop; provide Spaces). The two settings below override it.
`share_desktop` / `shareDesktop`	`Option<bool>`	`None`	Share this machine's own desktop as a Space.
`provide_spaces` / `provideSpaces`	`Option<bool>`	`None`	Create Spaces for your enrolled devices on this machine (relay mode).

`HostSpacesAuditRecord` record#

One line of this machine's Spaces audit (remote creates, deletes, refusals and settings changes).

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

`HostStatus` record#

Host status.

Returned by Host.configure, Host.setup, Host.start_sharing, Host.status, Host.stop_sharing.

Field	Type	Default	Description
`configured`	`bool`		Set up.
`mode`	`Option<String>`		`relay` or `direct`.
`relay_url` / `relayUrl`	`Option<String>`		Relay URL.
`direct_url` / `directUrl`	`Option<String>`		Direct URL.
`env_token_path` / `envTokenPath`	`Option<String>`		Env token file (direct mode).
`machine_id` / `machineId`	`Option<String>`		Machine id.
`name`	`Option<String>`		Name.
`sharing`	`bool`		Accepting clients.
`service_installed` / `serviceInstalled`	`bool`		Service installed.
`service_running` / `serviceRunning`	`bool`		Service running.
`service_kind` / `serviceKind`	`String`		Runner kind.
`online`	`Option<bool>`		Online at the relay.
`clients`	`Vec<RelayClientInfo>`		Connected clients.
`allow`	`Vec<String>`		Allowlist.
`permissions`	`Vec<HostPermission>`		Permission panes (macOS).
`error`	`Option<String>`		Relay error.
`recent_access` / `recentAccess`	`Vec<HostAccessRecord>`	`[]`	Who reached this machine recently, newest first (the driver's hash-chained access log).
`access_log_error` / `accessLogError`	`Option<String>`	`None`	Set when the access log does not verify (edited or truncated).
`share_desktop` / `shareDesktop`	`bool`	`true`	This machine's desktop is a Space.
`provide_spaces` / `provideSpaces`	`bool`	`false`	This machine provides Spaces to your other devices.
`max_spaces` / `maxSpaces`	`u32`	`0`	Provided Spaces at once (0: no limit).
`max_macos_vms` / `maxMacosVms`	`u32`	`0`	macOS VMs at once (at most two).
`provided_spaces` / `providedSpaces`	`Vec<HostProvidedSpace>`	`[]`	The Spaces this machine provides now.
`spaces_audit` / `spacesAudit`	`Vec<HostSpacesAuditRecord>`	`[]`	The Spaces audit, newest first.
`spaces_audit_error` / `spacesAuditError`	`Option<String>`	`None`	Set when the Spaces audit does not verify.

`RelayClientInfo` record#

Somebody connected to a machine through the relay.

Field	Type	Description
`id`	`String`	User id.
`email`	`Option<String>`	Email, when shared by the identity provider.
`name`	`Option<String>`	Display name.
`streams`	`u32`	Open streams.
`since`	`u64`	Unix seconds of the first open stream.

`RelayMachine` record#

A machine of the account's relay directory (relay:<id>).

Returned by Devices.confirm_machine, Relay.machine, Relay.machines, Relay.start_sharing, Relay.stop_sharing.

Field	Type	Description
`id`	`String`	Machine id.
`space_id` / `spaceId`	`String`	`relay:<id>`.
`name`	`String`	Display name.
`owner_id` / `ownerId`	`String`	Owner account id.
`owner_email` / `ownerEmail`	`Option<String>`	Owner email.
`role`	`String`	`owner` or `shared`.
`online`	`bool`	Connected to the relay.
`sharing`	`bool`	Accepting clients.
`version`	`String`	spacesd version.
`url`	`String`	`<relay>/m/<id>`.
`allow`	`Vec<String>`	Allowlist (owner view only).
`clients`	`Vec<RelayClientInfo>`	Connected clients.
`confirmed`	`bool`	Registered with an enrolled device's signature or MFA, or confirmed since from one; `true` for anything a relay registered before this check existed. `false` shows the machine as "new" until an enrolled device confirms it (`Devices.confirm_machine`) (S5).

Host and relay

Host#

Host.new#

Host.configure#

Host.remove#

Host.setup#

Host.start_sharing#

Host.status#

Host.stop_sharing#

Relay#

Relay.new#

Relay.connect#

Relay.machine#

Relay.machines#

Relay.start_sharing#

Relay.stop_sharing#

HostAccessRecord record#

HostPermission record#

HostProvidedSpace record#

HostSettingsChange record#

HostSetupOptions record#

HostSpacesAuditRecord record#

HostStatus record#

RelayClientInfo record#

RelayMachine record#

Host#

Host.new#

Host.configure#

Host.remove#

Host.setup#

Host.start_sharing#

Host.status#

Host.stop_sharing#

Relay#

Relay.new#

Relay.connect#

Relay.machine#

Relay.machines#

Relay.start_sharing#

Relay.stop_sharing#

HostAccessRecord record#

HostPermission record#

HostProvidedSpace record#

HostSettingsChange record#

HostSetupOptions record#

HostSpacesAuditRecord record#

HostStatus record#

RelayClientInfo record#

RelayMachine record#

`Host`#

`Host.new`#

`Host.configure`#

`Host.remove`#

`Host.setup`#

`Host.start_sharing`#

`Host.status`#

`Host.stop_sharing`#

`Relay`#

`Relay.new`#

`Relay.connect`#

`Relay.machine`#

`Relay.machines`#

`Relay.start_sharing`#

`Relay.stop_sharing`#

`HostAccessRecord` record#

`HostPermission` record#

`HostProvidedSpace` record#

`HostSettingsChange` record#

`HostSetupOptions` record#

`HostSpacesAuditRecord` record#

`HostStatus` record#

`RelayClientInfo` record#

`RelayMachine` record#

`Host`#

`Host.new`#

`Host.configure`#

`Host.remove`#

`Host.setup`#

`Host.start_sharing`#

`Host.status`#

`Host.stop_sharing`#

`Relay`#

`Relay.new`#

`Relay.connect`#

`Relay.machine`#

`Relay.machines`#

`Relay.start_sharing`#

`Relay.stop_sharing`#

`HostAccessRecord` record#

`HostPermission` record#

`HostProvidedSpace` record#

`HostSettingsChange` record#

`HostSetupOptions` record#

`HostSpacesAuditRecord` record#

`HostStatus` record#

`RelayClientInfo` record#

`RelayMachine` record#