Host, relay and devices

Unattended host setup, the cua-relay directory client, and this device's enrollment on the relay.

Set this machine up for unattended access, and reach account machines through the relay. Spaces.hosts lists your computers that provide Spaces (SpacesHost), with their limits and how busy each one is.

`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).
`migrate_service`	macOS: moves the host service from the old LaunchAgent to the Cua Spaces app (its own login item, "Cua Spaces"), keeping this machine's registration, id and Spaces; puts the old one back if the helper does not take over (the outcome says so).
`pause_signed_out`	Pause relay sharing while nobody is signed in to the owner's account: the host leaves the relay and stays off it (also across a restart) with its setup kept.
`remove`	Unregister, uninstall the service and delete the host state.
`resume_signed_in`	Resume relay sharing paused by `Host.pause_signed_out` once `account` (the signed-in account's id or email) is signed in; refused when it is not the machine's owner.
`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.migrate_service`#

macOS: moves the host service from the old LaunchAgent to the Cua Spaces app (its own login item, "Cua Spaces"), keeping this machine's registration, id and Spaces; puts the old one back if the helper does not take over (the outcome says so). app_version: a failed move is not tried again by itself with the same version; force tries anyway.

async def migrate_service(self, force: bool, app_version: str) -> HostServiceMigration

Parameter	Type	Default
`force`	`bool`	required
`app_version`	`String`	required

Returns HostServiceMigration · Async · Raises CuaError

`Host.pause_signed_out`#

Pause relay sharing while nobody is signed in to the owner's account: the host leaves the relay and stays off it (also across a restart) with its setup kept. Direct mode is left alone.

async def pause_signed_out(self) -> HostStatus

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

Resume relay sharing paused by Host.pause_signed_out once account (the signed-in account's id or email) is signed in; refused when it is not the machine's owner.

async def resume_signed_in(self, account: str) -> HostStatus

Parameter	Type	Default
`account`	`String`	required

Returns HostStatus · 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` = the relay `cua` uses: `CUA_RELAY_URL`, else this machine's host setup, 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 = the relay cua uses: CUA_RELAY_URL, else this machine's host setup, 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

`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.
`load`	`Option<SpacesHostLoad>`	How busy it is, when it answered and reports it.

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

`SpacesHostLoad` record#

How busy one of your machines is (its job runner's view).

Field	Type	Description
`millicpus_total` / `millicpusTotal`	`u32`	CPU it offers, in thousandths.
`millicpus_free` / `millicpusFree`	`u32`	Of that, free.
`memory_total_mb` / `memoryTotalMb`	`u64`	Memory it offers (MiB).
`memory_free_mb` / `memoryFreeMb`	`u64`	Of that, free.
`spaces`	`u32`	Spaces running there.
`problem`	`String`	Why it takes nothing now (empty: it does).
`kinds`	`Vec<String>`	The kinds it creates (`container`, `vm`, `microvm`), as it reports them; empty when it does not say.

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

`HostServiceMigration` record#

What Host.migrate_service did.

Returned by Host.migrate_service.

Field	Type	Description
`outcome`	`String`	`migrated`, `switched`, `cleaned-up`, `rolled-back`, `kept` or `not-needed`.
`detail`	`String`	In words.
`permissions_needed` / `permissionsNeeded`	`bool`	macOS will ask for Screen Recording and Accessibility for Cua Spaces Helper.

`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).
`max_memory_gb` / `maxMemoryGb`	`Option<u32>`	`None`	Memory the provided Spaces may use in total, in GB (0: no limit).
`max_disk_gb` / `maxDiskGb`	`Option<u32>`	`None`	Disk the provided Spaces may use in total, in GB (0: no limit).
`max_run_minutes` / `maxRunMinutes`	`Option<u32>`	`None`	How long a provided Space may run, in minutes (0: no limit).

`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). `None`: on for a machine set up for the first time through the relay; a machine set up before keeps its setting.

`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.pause_signed_out, Host.resume_signed_in, 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).
`max_memory_gb` / `maxMemoryGb`	`u32`	`0`	Memory the provided Spaces may use in total, in GB (0: no limit).
`max_disk_gb` / `maxDiskGb`	`u32`	`0`	Disk the provided Spaces may use in total, in GB (0: no limit).
`max_run_minutes` / `maxRunMinutes`	`u32`	`0`	How long a provided Space may run, in minutes (0: no limit).
`used_memory_gb` / `usedMemoryGb`	`u32`	`0`	What the provided Spaces were given now, in GB.
`used_disk_gb` / `usedDiskGb`	`u32`	`0`
`total_memory_gb` / `totalMemoryGb`	`u32`	`0`	This machine's own memory and disk, in GB (0: not known).
`total_disk_gb` / `totalDiskGb`	`u32`	`0`
`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.
`paused_signed_out` / `pausedSignedOut`	`bool`	`false`	Relay sharing is paused until the owner signs in again (`Host.pause_signed_out`).
`owner`	`Option<String>`	`None`	The account this machine is registered to (relay mode): its id.
`owner_email` / `ownerEmail`	`Option<String>`	`None`	The owner's email, when the relay gave one.
`helper_available` / `helperAvailable`	`bool`	`false`	macOS: a Cua Spaces app that can run the host service is installed, so the host service can run as it.
`legacy_service` / `legacyService`	`bool`	`false`	macOS: the old hand-written LaunchAgent is still there.

`PairingCode` record#

A one-time code that adds a machine to the account ("Add a machine" by link or QR code).

Returned by Devices.create_pairing_code, Devices.pairing_codes.

Field	Type	Description
`id`	`String`	`pc_…` (to revoke it).
`code`	`Option<String>`	`XXXX-XXXX-XXXX`: only when just made.
`url`	`Option<String>`	`https://cua.ai/add/<code>` (the link and the QR code): only when just made.
`install_sh` / `installSh`	`Option<String>`	`curl … \| sh -s -- --pair <code>` (macOS, Linux): only when just made.
`install_powershell` / `installPowershell`	`Option<String>`	The PowerShell one-liner (Windows): only when just made.
`state`	`String`	`active`, `used`, `revoked` or `expired`.
`team`	`Option<String>`	Team the machine is added for.
`created_at` / `createdAt`	`u64`	Unix seconds.
`expires_at` / `expiresAt`	`u64`	Unix seconds.
`used_at` / `usedAt`	`Option<u64>`	When a machine used it.
`machine`	`Option<String>`	The machine it added (relay machine id).

`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, Devices.rename_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).
`team`	`Option<String>`	The team you reach it through, for a team machine not shared with you directly.
`provides_spaces` / `providesSpaces`	`Option<bool>`	It creates Spaces for its owner's devices, when it said so at registration (`None` from a host or relay that predates it).

This device on the relay#

auth.devices(relay_url, name) returns this device on the relay, its key in the session's credential store (shared with the cua CLI and daemon). A device lists and reaches the account's machines once enrolled: right after a fresh sign-in (a sign-in through Auth.begin_login re-registers a device that already has a key), or by a one-time code approved from an enrolled device (cua devices approve). A new key of the same machine replaces its old record. Enrollment lasts 30 days, then one approval or a fresh sign-in re-verifies it. Nothing here prompts; gate approve behind presence in your UI.

`Devices`#

This device as a client of the signed-in account on a relay: its enrollment, the account's other devices and its audit log. The device key lives in the session's vault (shared with the cua CLI and daemon). Nothing here prompts: approving is the caller's to gate behind presence.

Returned by Auth.devices.

Method	Description
`approve`	Approves the device showing `code`, or re-verifies `device_id`, from this enrolled device.
`check_enrolled`	Whether the relay lets this device open a session now (enrolled), asked afresh.
`confirm_machine`	Vouches for `machine_id`, a machine that registered without an enrolled device's signature or MFA (from this enrolled device) (S5).
`create_pairing_code`	Makes a one-time code (link, QR, install commands) that adds another computer to the account, or to `team` (from this enrolled device).
`device_id`	This device's id, when it has a key (no network).
`enroll`	Registers this device (creating its key on first use).
`pairing_codes`	The account's pairing codes, newest first (without the codes).
`rename`	Renames a device (from this enrolled device).
`rename_machine`	Renames `machine_id`, a machine the account owns, on the relay (from this enrolled device).
`revoke`	Revokes a device (from this enrolled device).
`revoke_pairing_code`	Revokes an unused pairing code (`pc_…`).
`snapshot`	The account's devices, the grace period, the newest `audit_limit` audit events and the machines' names.
`resolve_default_space`	Where the default Space resolves now: the first online entry of the default, the fallback order, then this computer (its own relay machine id, when it has one).
`set_spaces_settings`	Replaces the account's default Space settings (the whole object; `updated_at` is set by the relay).
`spaces_settings`	The account's default Space and fallback order.

Accessor	Returns	Description
`relay_url()`	`String`	The relay base URL.

`Devices.approve`#

Approves the device showing code, or re-verifies device_id, from this enrolled device.

async def approve(self, code: Optional[str], device_id: Optional[str]) -> RelayDevice

Parameter	Type	Default
`code`	`Option<String>`	required
`device_id`	`Option<String>`	required

Returns RelayDevice · Async · Raises CuaError

`Devices.check_enrolled`#

Whether the relay lets this device open a session now (enrolled), asked afresh. Polled while waiting for an approval.

async def check_enrolled(self) -> bool

Returns bool · Async

`Devices.confirm_machine`#

Vouches for machine_id, a machine that registered without an enrolled device's signature or MFA (from this enrolled device) (S5). Clears RelayMachine.confirmed's "new" flag for every account member, not just this device.

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

Parameter	Type	Default
`machine_id`	`String`	required

Returns RelayMachine · Async · Raises CuaError

`Devices.create_pairing_code`#

Makes a one-time code (link, QR, install commands) that adds another computer to the account, or to team (from this enrolled device). It expires after ttl_secs (30 minutes when None).

async def create_pairing_code(self, team: Optional[str], ttl_secs: Optional[int]) -> PairingCode

Parameter	Type	Default
`team`	`Option<String>`	required
`ttl_secs`	`Option<u64>`	required

Returns PairingCode · Async · Raises CuaError

`Devices.device_id`#

This device's id, when it has a key (no network).

def device_id(self) -> Optional[str]

Returns Option<String> · Raises CuaError

`Devices.enroll`#

Registers this device (creating its key on first use). Right after a fresh sign-in it is enrolled at once (replacing this machine's older device key, if any); otherwise the result carries a one-time code to approve from an enrolled device.

async def enroll(self) -> DeviceEnrollment

Returns DeviceEnrollment · Async · Raises CuaError

`Devices.pairing_codes`#

The account's pairing codes, newest first (without the codes).

async def pairing_codes(self) -> List[PairingCode]

Returns Vec<PairingCode> · Async · Raises CuaError

`Devices.rename`#

Renames a device (from this enrolled device).

async def rename(self, id: str, name: str) -> RelayDevice

Parameter	Type	Default
`id`	`String`	required
`name`	`String`	required

Returns RelayDevice · Async · Raises CuaError

`Devices.rename_machine`#

Renames machine_id, a machine the account owns, on the relay (from this enrolled device). When it is this machine's own registration, its host setup takes the new name too.

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

Parameter	Type	Default
`machine_id`	`String`	required
`name`	`String`	required

Returns RelayMachine · Async · Raises CuaError

`Devices.revoke`#

Revokes a device (from this enrolled device). Revoking this device also deletes its key.

async def revoke(self, id: str) -> RelayDevice

Parameter	Type	Default
`id`	`String`	required

Returns RelayDevice · Async · Raises CuaError

`Devices.revoke_pairing_code`#

Revokes an unused pairing code (pc_…).

async def revoke_pairing_code(self, id: str) -> None

Parameter	Type	Default
`id`	`String`	required

Async · Raises CuaError

`Devices.snapshot`#

The account's devices, the grace period, the newest audit_limit audit events and the machines' names. Only the device list must succeed; the rest is empty when the relay refuses it.

async def snapshot(self, audit_limit: int) -> DevicesSnapshot

Parameter	Type	Default
`audit_limit`	`u32`	required

Returns DevicesSnapshot · Async · Raises CuaError

`DevicesSnapshot` record#

Everything the Devices page reads, in one call.

Returned by Devices.snapshot.

Field	Type	Description
`local_device_id` / `localDeviceId`	`Option<String>`	This device's id, when it has a key.
`devices`	`Vec<RelayDevice>`	The account's devices (this one marked `current` once enrolled).
`enforce_after` / `enforceAfter`	`Option<u64>`	End of the relay's grace period for unenrolled devices.
`audit`	`Vec<RelayAuditEvent>`	The account's audit log, newest last (empty when the relay refuses).
`machine_names` / `machineNames`	`HashMap<String, String>`	Machine ids to names (empty when this device cannot list them).
`machines`	`Vec<RelayMachine>`	The account's relay machines, `RelayMachine.confirmed` included (S5; empty when this device cannot list them, same as `machine_names`).

`RelayDevice` record#

A client device of the account, as the relay lists it.

Returned by Devices.approve, Devices.rename, Devices.revoke.

Field	Type	Description
`id`	`String`	`dev_…`.
`name`	`String`	Display name.
`state`	`String`	`pending`, `enrolled`, `expired` or `revoked`.
`platform`	`String`	Operating system it reported (`macos`, `windows`, `linux`); empty when unknown.
`created_at` / `createdAt`	`u64`	Registered at (Unix seconds).
`enrolled_until` / `enrolledUntil`	`Option<u64>`	Re-verification due at (Unix seconds).
`last_seen` / `lastSeen`	`Option<u64>`	Last session (Unix seconds).
`current`	`bool`	This device.

`RelayAuditEvent` record#

One event of the account's audit log.

Field	Type	Description
`ts`	`u64`	Unix seconds.
`kind`	`String`	Kind (`machine_access`, `device_enrolled`, `share_added`, ...).
`device`	`Option<String>`	Acting device.
`machine`	`Option<String>`	Machine id.
`subject`	`Option<String>`	Other party.
`detail`	`Option<String>`	Detail.

`DeviceEnrollment` record#

Devices.enroll's result.

Returned by Devices.enroll.

Field	Type	Description
`device`	`RelayDevice`	This device.
`enrolled`	`bool`	Enrolled now (right after a fresh sign-in).
`code`	`Option<String>`	The one-time code to approve from an enrolled device otherwise.

Computer health#

Spaces.machine_health asks a computer's cua daemon to check it (this computer with None, another of yours by id or name over the relay, the mesh or its direct address). The Computers page shows the warnings and failures as the computer's issues; cua doctor --machine prints them.

Check a computer#

Methods of Spaces.

`Spaces.machine_health`#

A machine's health as its own cua daemon checks it: Local Network access (and which app macOS holds responsible), free disk, virtualization, memory left by running Spaces, the permissions sharing its desktop needs. machine: another of your machines, by id or name (asked over the relay, the mesh or its direct address); None for this one. Read-only; fails plainly when that machine is offline, not yours, or runs a Cua that predates the check.

async def machine_health(self, machine: Optional[str]) -> MachineHealth

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

Returns MachineHealth · Async · Raises CuaError

`MachineHealth` record#

A machine's health as its own cua daemon checks it.

Returned by Spaces.machine_health.

Field	Type	Description
`cua_version` / `cuaVersion`	`String`	The Cua version of the daemon that checked.
`os`	`String`	`macos`, `linux`, `windows`.
`checks`	`Vec<MachineHealthCheck>`	Every check, in order.
`report_json` / `reportJson`	`String`	The whole report as JSON (the schema `cua doctor --json` writes).

`MachineHealthCheck` record#

One check of a machine's health (Spaces.machine_health).

Field	Type	Description
`id`	`String`	`machine.local_network`, `machine.disk`, `machine.virtualization`, `machine.memory`, `machine.permissions.<id>`.
`status`	`String`	`pass`, `warn`, `fail` or `skip`.
`message`	`String`	What it found, in one line.
`remediation`	`String`	What to do about a warning or failure.
`facts`	`HashMap<String, String>`	What a UI needs to word it and offer its fix (`app`, `settings_url`, `free_gb`, ...).

Host, relay and devices

Host#

Host.new#

Host.configure#

Host.migrate_service#

Host.pause_signed_out#

Host.remove#

Host.resume_signed_in#

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#

SpacesHost record#

SpacesHostLimit record#

SpacesHostLoad record#

HostAccessRecord record#

HostPermission record#

HostProvidedSpace record#

HostServiceMigration record#

HostSettingsChange record#

HostSetupOptions record#

HostSpacesAuditRecord record#

HostStatus record#

PairingCode record#

RelayClientInfo record#

RelayMachine record#

This device on the relay#

Devices#

Devices.approve#

Devices.check_enrolled#

Devices.confirm_machine#

Devices.create_pairing_code#

Devices.device_id#

Devices.enroll#

Devices.pairing_codes#

Devices.rename#

Devices.rename_machine#

Devices.revoke#

Devices.revoke_pairing_code#

Devices.snapshot#

DevicesSnapshot record#

RelayDevice record#

RelayAuditEvent record#

DeviceEnrollment record#

Computer health#

Check a computer#

Spaces.machine_health#

MachineHealth record#

MachineHealthCheck record#

`Host`#

`Host.new`#

`Host.configure`#

`Host.migrate_service`#

`Host.pause_signed_out`#

`Host.remove`#

`Host.resume_signed_in`#

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

`SpacesHost` record#

`SpacesHostLimit` record#

`SpacesHostLoad` record#

`HostAccessRecord` record#

`HostPermission` record#

`HostProvidedSpace` record#

`HostServiceMigration` record#

`HostSettingsChange` record#

`HostSetupOptions` record#

`HostSpacesAuditRecord` record#

`HostStatus` record#

`PairingCode` record#

`RelayClientInfo` record#

`RelayMachine` record#

`Devices`#

`Devices.approve`#

`Devices.check_enrolled`#

`Devices.confirm_machine`#

`Devices.create_pairing_code`#

`Devices.device_id`#

`Devices.enroll`#

`Devices.pairing_codes`#

`Devices.rename`#

`Devices.rename_machine`#

`Devices.revoke`#

`Devices.revoke_pairing_code`#

`Devices.snapshot`#

`DevicesSnapshot` record#

`RelayDevice` record#

`RelayAuditEvent` record#

`DeviceEnrollment` record#

`Spaces.machine_health`#

`MachineHealth` record#

`MachineHealthCheck` record#