Sharing
Let other cua.ai accounts watch or edit a Space, through the relay.
Let other cua.ai accounts watch or edit a Space, through the relay.
| Tool | Description |
|---|---|
share_space | Let another cua.ai account watch or edit a Space. |
unshare_space | Stop sharing a Space with an account, or with everyone. |
space_shares | List who a Space is shared with. |
relay_register_space | Publish a Space on the relay for the account's other devices. |
relay_unregister_space | Take a Space off the relay. |
Let another cua.ai account watch or edit a Space.
Shares the Space through the cua.ai relay with one account, by verified email or account id; the same allowlist and device enrollment cua host share uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (relay:<id>) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open invitee_space.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:share_space; mutating, idempotent |
| Requires (this machine) | relay_account |
| Swift SDK | space.sharing.share(with:role:) |
| Rust | Spaces::share_space |
| Parameter | Type | Default | Description |
|---|---|---|---|
role | string | viewer | viewer (presence with their own cursor and a view-only stream) or editor (full use; their input is a human session). Default viewer. |
space | string | required | Space id or name. |
who | string | required | Who: an email address (verified by cua.ai) or an account id. Teams are not accepted: share with each member. |
JSON: space, machine (the relay machine it is shared as; empty when not shared), invitee_space (what the people it is shared with open: relay:<machine>), url, online and shares (each who, role: viewer or editor, and connected).
invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, permission_denied, unauthenticated
Stop sharing a Space with an account, or with everyone.
Removes one account (or everyone) at once: the relay cuts their open streams and refuses new calls. With no who, the Space stops being shared and a Space that is not a host leaves the relay.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:unshare_space; mutating, idempotent |
| Requires (this machine) | relay_account |
| Swift SDK | space.sharing.unshare(_:) |
| Rust | Spaces::unshare_space |
| Parameter | Type | Default | Description |
|---|---|---|---|
space | string | required | Space id or name. |
who | string | none | The email or account id to remove. Default: everyone (the Space stops being shared; a Space that is not a host leaves the relay). |
JSON: space, machine (the relay machine it is shared as; empty when not shared), invitee_space (what the people it is shared with open: relay:<machine>), url, online and shares (each who, role: viewer or editor, and connected).
invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, permission_denied, unauthenticated
List who a Space is shared with.
Who the Space is shared with, in which role, and who of them is connected through the relay now.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:space_shares, in spaces:readonly; read-only, idempotent |
| Requires (this machine) | relay_account |
| Swift SDK | space.sharing.shares() |
| Rust | Spaces::space_shares |
| Parameter | Type | Default | Description |
|---|---|---|---|
audit | integer | 0 | Also return this many of the newest owner-side audit lines. Default 0. At least 0. |
space | string | required | Space id or name. |
JSON: the shares (see share_space) and, with audit, audit: the newest owner-side lines (ts_ms, action: share, unshare, attach or detach, space, detail).
invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, unauthenticated
Publish a Space on the relay for the account's other devices.
Publishes the Space as a machine of the signed-in account on the cua.ai relay, the way cua host setup publishes this computer: the Space's own driver joins the relay over outbound WSS with a machine token the account registered, so no inbound port is opened. The account's other devices (a phone off this network, the Cua app on another computer) then open relay_space; nobody else can until share_space adds them. Idempotent, and it re-attaches a Space that restarted. Needs a driver with relay_attach (a host is already registered).
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:relay_register_space; mutating, idempotent |
| Requires (this machine) | relay_account |
| Swift SDK | spaces.relay.register(_:) |
| Rust | Spaces::relay_register |
| Parameter | Type | Default | Description |
|---|---|---|---|
space | string | required | Space id or name. |
JSON: space, relay_space (relay:<machine>: how the account's other devices reach it), machine, url and online.
invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, unauthenticated
Take a Space off the relay.
Takes the Space off the relay: its driver leaves and its machine is removed, with every share. A host is removed with cua host remove on that machine instead.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:relay_unregister_space; mutating, idempotent |
| Requires (this machine) | relay_account |
| Swift SDK | spaces.relay.unregister(_:) |
| Rust | Spaces::relay_unregister |
| Parameter | Type | Default | Description |
|---|---|---|---|
space | string | required | Space id or name. |
JSON: space and unregistered (false when it was not on the relay).
invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, unauthenticated