# Spaces

The Spaces registry: create, add, resolve, delete and remove Spaces.

> Agent discovery: use [the Cua documentation index](https://cua.ai/docs/llms.txt) to find related pages and their Markdown URLs.







`cua.spaces()` returns the `Spaces` registry. Create a Space where `on` says (local or cloud), or add an existing machine by URL, then open a [`Space`](</docs/cua-sdk/reference/spaces/space>).

## `Spaces`

The Spaces registry: add a machine by URL, claim a Fleet Space,
provision a local one, and get `Space` handles.

Returned by [`Cua.spaces`](</docs/cua-sdk/reference/cua#cua>).

| Method | Description |
| --- | --- |
| [`add`](#spacesadd) | Adds a Space by URL (`http(s)://host:port`, `host:port`, or a Space id such as `local:<name>`) after a `GetCapabilities` handshake. |
| [`add_with_service`](#spacesadd_with_service) | `Spaces.add`, naming the service a plain MCP endpoint is registered under (default `mcp`). |
| [`call_tool_json`](#spacescall_tool_json) | Calls any Spaces MCP tool with JSON arguments (the implementation `cua daemon mcp` serves). |
| [`cancel_create`](#spacescancel_create) | Cancels a create that is still running: `space` is the create's `create_id`, the id the Space will have (`local:<name>`, carried by every progress report) or its name. |
| [`create`](#spacescreate) | Creates a Space where `options.on` says (the user default when unset): a new sandbox registered as a Space. |
| [`create_with_progress`](#spacescreate_with_progress) | `Spaces.create`, reporting what it does to `listener` (pulling the image, booting, waiting for cua-spacesd, connecting) until the Space is ready. |
| [`delete`](#spacesdelete) | Deletes a Space's sandbox and forgets it (a Space added by address is only forgotten). |
| [`gpu_support`](#spacesgpu_support) | The GPU options each runtime of `on` (`local` by default, or `cloud`) offers on this host: Lume's "GPU acceleration" for macOS VMs (experimental, Apple silicon), QEMU's virgl and containers' NVIDIA GPUs on Linux. |
| [`hosts`](#spaceshosts) | Your machines that provide Spaces (the account's relay hosts, then the hosts added by their Tailscale or LAN address), each asked for its limits: what `create` takes as `on="host:<id>"`. |
| [`list`](#spaceslist) | Registered Spaces. |
| [`list_tools_json`](#spaceslist_tools_json) | The Spaces MCP `tools/list` result as JSON (the contract). |
| [`relay_register`](#spacesrelay_register) | Publishes `space` on the cua.ai relay as a machine of the signed-in account, the way `cua host setup` publishes this computer: the Space's own driver dials out, so the account's other devices (a phone off this network) reach it as `relay:<machine>`, and nobody else until it is shared. |
| [`relay_unregister`](#spacesrelay_unregister) | Takes `space` off the relay (its driver leaves; every share goes). |
| [`remove`](#spacesremove) | Unregisters a Space (the sandbox is not touched). |
| [`resolve`](#spacesresolve) | Resolves an id, legacy id, URL or display name. |
| [`space`](#spacesspace) | A connected handle to a registered Space. |
| [`start`](#spacesstart) | Turns a Space on again: resumes a suspended one, boots a stopped one (a Space one of your machines provides joins the relay again), and leaves a running one as it is. |
| [`stop`](#spacesstop) | Turns a Space off the way its provider can (`SpaceInfo.power`): suspends it, keeping its memory (a local container or QEMU VM), or stops it, keeping its disk (a local Lume VM; a Space one of your machines provides, which that machine stops). |
| [`agent_capabilities`](</docs/cua-sdk/reference/spaces/agents#spacesagent_capabilities>) | What every agent harness is and cannot do (`agent_capabilities`), as JSON. |
| [`agent_pause`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesagent_pause>) | Pauses a persistent agent: run, routines and (local) Space. |
| [`agent_resume`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesagent_resume>) | Resumes a paused persistent agent; with `prompt`, starts a run. |
| [`cloud_connect`](</docs/cua-sdk/reference/spaces/cloud#spacescloud_connect>) | Connects a cloud account (after the checks `cloud_test` runs). |
| [`cloud_disconnect`](</docs/cua-sdk/reference/spaces/cloud#spacescloud_disconnect>) | Forgets a connected cloud (nothing in it is deleted). |
| [`cloud_status`](</docs/cua-sdk/reference/spaces/cloud#spacescloud_status>) | Your clouds: found credentials, the connected account and region, what each can run at what hourly cost, and what Cua created there. |
| [`cloud_sweep`](</docs/cua-sdk/reference/spaces/cloud#spacescloud_sweep>) | What Cua left in your clouds (expired Spaces, resources whose Space is gone; with `all`, everything Cua created there). |
| [`cloud_test`](</docs/cua-sdk/reference/spaces/cloud#spacescloud_test>) | Checks a cloud account without creating anything. |
| [`computer_access`](</docs/cua-sdk/reference/spaces/persistent-agents#spacescomputer_access>) | Per-agent computer grants (of one agent, or all). |
| [`computer_access_grant`](</docs/cua-sdk/reference/spaces/persistent-agents#spacescomputer_access_grant>) | Lets one persistent agent use one of the user's computers (asks for presence). |
| [`computer_access_revoke`](</docs/cua-sdk/reference/spaces/persistent-agents#spacescomputer_access_revoke>) | Takes a persistent agent's computer access back (every machine when `machine` is empty). |
| [`notifications`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesnotifications>) | The notifications feed, newest first. |
| [`notifications_ack`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesnotifications_ack>) | Marks notifications read (every one when `ids` is empty). |
| [`notify_user`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesnotify_user>) | Posts a notification to the Cua app. |
| [`persistent_agent_create`](</docs/cua-sdk/reference/spaces/persistent-agents#spacespersistent_agent_create>) | Creates a persistent agent: `harness` working in `space`, its home at `agents/<name>/` in the Cua Volume. |
| [`persistent_agent_remove`](</docs/cua-sdk/reference/spaces/persistent-agents#spacespersistent_agent_remove>) | Forgets a persistent agent (its home stays in the drive). |
| [`persistent_agent_save`](</docs/cua-sdk/reference/spaces/persistent-agents#spacespersistent_agent_save>) | Saves a persistent agent's home into the drive now. |
| [`persistent_agent_send`](</docs/cua-sdk/reference/spaces/persistent-agents#spacespersistent_agent_send>) | Gives a persistent agent a turn: a follow-up to its idle run, or a new run with its home restored. |
| [`persistent_agents`](</docs/cua-sdk/reference/spaces/persistent-agents#spacespersistent_agents>) | Every persistent agent. |
| [`routine_add`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesroutine_add>) | Adds a routine. |
| [`routine_remove`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesroutine_remove>) | Deletes a routine. |
| [`routine_set_enabled`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesroutine_set_enabled>) | Turns a routine on or off. |
| [`routines`](</docs/cua-sdk/reference/spaces/persistent-agents#spacesroutines>) | Routines (of one agent, or all). |
| [`volume_approve`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_approve>) | `volume_approve`: the request becomes a grant (with presence). |
| [`volume_audit`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_audit>) | `volume_audit`: the newest events (default 50) and whether the log verified. |
| [`volume_cache_clear`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_cache_clear>) | `volume_cache_clear`: drops every cached block. |
| [`volume_cache_set`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_cache_set>) | `volume_cache_set`: the cache's size cap (at least 256 MiB). |
| [`volume_cache_stats`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_cache_stats>) | `volume_cache_stats`: the block cache's size, cap and hit rate. |
| [`volume_delete`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_delete>) | `volume_delete`: a delete marker (history stays). |
| [`volume_deny`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_deny>) | `volume_deny`. |
| [`volume_grant`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_grant>) | `volume_grant`: widens `principal`'s access (`agent:<name>` or `space:<id>`, mode `r` or `rw`). |
| [`volume_grants`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_grants>) | `volume_grants`: live grants (every grant with `all`). |
| [`volume_history`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_history>) | `volume_history`: a file's versions, newest first. |
| [`volume_ls`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_ls>) | `volume_ls`: a folder's immediate children (default the root). |
| [`volume_mount`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_mount>) | `volume_mount`: turns the mount on (kept across restarts) and mounts. |
| [`volume_mount_status`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_mount_status>) | `volume_mount_status`: whether the drive is mounted as a volume. |
| [`volume_read`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_read>) | `volume_read`: a file (or one of its versions). |
| [`volume_request_access`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_request_access>) | `volume_request_access`: `agent` asks the user for more access. |
| [`volume_requests`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_requests>) | `volume_requests`: requests waiting for the user. |
| [`volume_restore`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_restore>) | `volume_restore`: makes an old version current again. |
| [`volume_revoke`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_revoke>) | `volume_revoke`. |
| [`volume_storage`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_storage>) | `volume_storage`: where the drive keeps its bytes. |
| [`volume_storage_set`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_storage_set>) | `volume_storage_set`: tests, and unless `dry_run` saves and switches to, a storage backend (live, no restart). |
| [`volume_sync_events`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_sync_events>) | `volume_sync_events`: events after `since_seq`, waiting up to `wait_ms` (at most 30000) for one. |
| [`volume_sync_resolve`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_sync_resolve>) | `volume_sync_resolve`: clears a conflict from the list (files stay). |
| [`volume_sync_status`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_sync_status>) | `volume_sync_status`: devices, pending uploads and conflicts. |
| [`volume_unmount`](</docs/cua-sdk/reference/spaces/volume-sync#spacesvolume_unmount>) | `volume_unmount`: turns the mount off; pending uploads land first. |
| [`volume_write`](</docs/cua-sdk/reference/spaces/volume#spacesvolume_write>) | `volume_write`: a new version of a file. |

### `Spaces.add`

Adds a Space by URL (`http(s)://host:port`, `host:port`, or a
Space id such as `local:<name>`) after a `GetCapabilities` handshake. Any other MCP
endpoint (`http://host:8765/mcp`) becomes a Space with one MCP
service, `mcp`, and no spacesd capabilities.




**Python**



```python
async def add(self, url: str, token: Optional[str], name: Optional[str]) -> SpaceInfo
```






**TypeScript**



```ts
add(url: string, token: string | undefined, name: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceInfo>
```






**Swift**



```swift
func add(url: String, token: String?, name: String?) async throws -> SpaceInfo
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun add(url: String, token: String?, name: String?): SpaceInfo
```






**Rust**



```rust
pub async fn add(&self, url: String, token: Option<String>, name: Option<String>) -> Result<SpaceInfo, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `url` | `String` | required |
| `token` | `Option<String>` | required |
| `name` | `Option<String>` | required |

**Returns** [`SpaceInfo`](#spaceinfo-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

**Example**






**Python**



```python test="docs" id="spaces-add-py" session="spaces-add-py" prelude="space-url"
import asyncio

import cua

async def main():
    spaces = cua.embedded().spaces()
    info = await spaces.add("http://10.0.0.5:3211", "TOKEN", "lab")  # a machine running cua-spacesd
    space = await spaces.space(info.id)
    out = await space.bash("echo hi", None)
    print([info.provider, out.stdout, out.exit_code])

asyncio.run(main())
```






**Swift**



```swift test="swift" id="spaces-add-swift"
import Cua

let spaces = try Cua.embedded().spaces()
let info = try await spaces.add(url: "http://10.0.0.5:3211", token: "TOKEN", name: "lab")  // a machine running cua-spacesd
let space = try await spaces.space(space: info.id)
let out = try await space.bash(command: "echo hi", timeoutMs: nil)
print(info.provider, out.stdout, out.exitCode ?? -1)
```






**Kotlin**



```kotlin test="kotlin" id="spaces-add-kt"
import ai.cua.sdk.Cua
import ai.cua.sdk.CuaConfig

val spaces = Cua.embedded(CuaConfig()).spaces()
val info = spaces.add("http://10.0.0.5:3211", "TOKEN", "lab") // a machine running cua-spacesd
val space = spaces.space(info.id)
val out = space.bash("echo hi", null)
println("${info.provider} ${out.stdout} ${out.exitCode}")
```






### `Spaces.add_with_service`

`Spaces.add`, naming the service a plain MCP endpoint is
registered under (default `mcp`).




**Python**



```python
async def add_with_service(self, url: str, token: Optional[str], name: Optional[str], service: Optional[str]) -> SpaceInfo
```






**TypeScript**



```ts
addWithService(url: string, token: string | undefined, name: string | undefined, service: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceInfo>
```






**Swift**



```swift
func addWithService(url: String, token: String?, name: String?, service: String?) async throws -> SpaceInfo
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun addWithService(url: String, token: String?, name: String?, service: String?): SpaceInfo
```






**Rust**



```rust
pub async fn add_with_service(&self, url: String, token: Option<String>, name: Option<String>, service: Option<String>) -> Result<SpaceInfo, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `url` | `String` | required |
| `token` | `Option<String>` | required |
| `name` | `Option<String>` | required |
| `service` | `Option<String>` | required |

**Returns** [`SpaceInfo`](#spaceinfo-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.call_tool_json`

Calls any Spaces MCP tool with JSON arguments (the implementation
`cua daemon mcp` serves). Tool errors are returned, not raised.




**Python**



```python
async def call_tool_json(self, tool: str, arguments_json: Optional[str]) -> SpaceToolResult
```






**TypeScript**



```ts
callToolJson(tool: string, argumentsJson: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceToolResult>
```






**Swift**



```swift
func callToolJson(tool: String, argumentsJson: String?) async throws -> SpaceToolResult
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun callToolJson(tool: String, argumentsJson: String?): SpaceToolResult
```






**Rust**



```rust
pub async fn call_tool_json(&self, tool: String, arguments_json: Option<String>) -> Result<SpaceToolResult, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `tool` | `String` | required |
| `arguments_json` | `Option<String>` | required |

**Returns** [`SpaceToolResult`](</docs/cua-sdk/reference/spaces/space#spacetoolresult-record>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.cancel_create`

Cancels a create that is still running: `space` is the create's
`create_id`, the id the Space will have (`local:<name>`, carried by
every progress report) or its name. The work in flight stops (an
image download, a boot, a claim, a relay registration) and what the
create made is removed (its VM or container and disks, its cloud
claim, its relay machine); nothing that existed before is touched.
Finished image downloads stay cached, so the next create resumes.
Returns once the clean-up is done; the create itself fails with
`Cancelled`. Idempotent: a second call says `not_creating`. Works
for a create another process runs, and one a daemon restart cut off.




**Python**



```python
async def cancel_create(self, space: str) -> SpaceCancelOutcome
```






**TypeScript**



```ts
cancelCreate(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceCancelOutcome>
```






**Swift**



```swift
func cancelCreate(space: String) async throws -> SpaceCancelOutcome
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun cancelCreate(space: String): SpaceCancelOutcome
```






**Rust**



```rust
pub async fn cancel_create(&self, space: String) -> Result<SpaceCancelOutcome, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** [`SpaceCancelOutcome`](</docs/cua-sdk/reference/spaces/create#spacecanceloutcome-record>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>) ([`Cancelled`](</docs/cua-sdk/reference/errors#cancelled>))

### `Spaces.create`

Creates a Space where `options.on` says (the user default when
unset): a new sandbox registered as a Space. An existing machine is
added with `Spaces.add`.




**Python**



```python
async def create(self, options: SpaceCreateOptions) -> SpaceCreateResult
```






**TypeScript**



```ts
create(options: SpaceCreateOptions, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceCreateResult>
```






**Swift**



```swift
func create(options: SpaceCreateOptions) async throws -> SpaceCreateResult
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun create(options: SpaceCreateOptions): SpaceCreateResult
```






**Rust**



```rust
pub async fn create(&self, options: SpaceCreateOptions) -> Result<SpaceCreateResult, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `options` | [`SpaceCreateOptions`](</docs/cua-sdk/reference/spaces/create#spacecreateoptions-record>) | required |

**Returns** [`SpaceCreateResult`](</docs/cua-sdk/reference/spaces/create#spacecreateresult-record>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.create_with_progress`

`Spaces.create`, reporting what it does to `listener` (pulling
the image, booting, waiting for cua-spacesd, connecting) until the
Space is ready. Always waits (`options.wait` is ignored). Through a
daemon that predates progress, the listener hears only `ready`.




**Python**



```python
async def create_with_progress(self, options: SpaceCreateOptions, listener: SpaceCreateListener) -> SpaceCreateResult
```






**TypeScript**



```ts
createWithProgress(options: SpaceCreateOptions, listener: SpaceCreateListener, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceCreateResult>
```






**Swift**



```swift
func createWithProgress(options: SpaceCreateOptions, listener: SpaceCreateListener) async throws -> SpaceCreateResult
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun createWithProgress(options: SpaceCreateOptions, listener: SpaceCreateListener): SpaceCreateResult
```






**Rust**



```rust
pub async fn create_with_progress(&self, options: SpaceCreateOptions, listener: Arc<dyn SpaceCreateListener>) -> Result<SpaceCreateResult, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `options` | [`SpaceCreateOptions`](</docs/cua-sdk/reference/spaces/create#spacecreateoptions-record>) | required |
| `listener` | [`SpaceCreateListener`](</docs/cua-sdk/reference/spaces/create#spacecreatelistener>) | required |

**Returns** [`SpaceCreateResult`](</docs/cua-sdk/reference/spaces/create#spacecreateresult-record>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.delete`

Deletes a Space's sandbox and forgets it (a Space added by address
is only forgotten). Returns what happened.




**Python**



```python
async def delete(self, space: str) -> str
```






**TypeScript**



```ts
delete_(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<string>
```






**Swift**



```swift
func delete(space: String) async throws -> String
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun delete(space: String): String
```






**Rust**



```rust
pub async fn delete(&self, space: String) -> Result<String, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** `String` · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.gpu_support`

The GPU options each runtime of `on` (`local` by default, or
`cloud`) offers on this host: Lume's "GPU acceleration" for macOS
VMs (experimental, Apple silicon), QEMU's virgl and containers'
NVIDIA GPUs on Linux. A runtime with no option says why.




**Python**



```python
async def gpu_support(self, on: Optional[str]) -> List[GpuSupport]
```






**TypeScript**



```ts
gpuSupport(on: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<Array<GpuSupport>>
```






**Swift**



```swift
func gpuSupport(on: String?) async throws -> [GpuSupport]
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun gpuSupport(on: String?): List<GpuSupport>
```






**Rust**



```rust
pub async fn gpu_support(&self, on: Option<String>) -> Result<Vec<GpuSupport>, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `on` | `Option<String>` | required |

**Returns** [`Vec<GpuSupport>`](</docs/cua-sdk/reference/spaces/create#gpusupport-record>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.hosts`

Your machines that provide Spaces (the account's relay hosts, then
the hosts added by their Tailscale or LAN address), each asked for
its limits: what `create` takes as `on="host:<id>"`. One that does
not answer is listed offline when it provided a Space before.




**Python**



```python
async def hosts(self) -> List[SpacesHost]
```






**TypeScript**



```ts
hosts(asyncOpts_?: { signal: AbortSignal }): Promise<Array<SpacesHost>>
```






**Swift**



```swift
func hosts() async throws -> [SpacesHost]
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun hosts(): List<SpacesHost>
```






**Rust**



```rust
pub async fn hosts(&self) -> Result<Vec<SpacesHost>, CuaError>
```






**Returns** [`Vec<SpacesHost>`](</docs/cua-sdk/reference/spaces/space#spaceshost-record>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.list`

Registered Spaces.




**Python**



```python
async def list(self) -> List[SpaceInfo]
```






**TypeScript**



```ts
list(asyncOpts_?: { signal: AbortSignal }): Promise<Array<SpaceInfo>>
```






**Swift**



```swift
func list() async throws -> [SpaceInfo]
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun list(): List<SpaceInfo>
```






**Rust**



```rust
pub async fn list(&self) -> Result<Vec<SpaceInfo>, CuaError>
```






**Returns** [`Vec<SpaceInfo>`](#spaceinfo-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.list_tools_json`

The Spaces MCP `tools/list` result as JSON (the contract).




**Python**



```python
async def list_tools_json(self) -> str
```






**TypeScript**



```ts
listToolsJson(asyncOpts_?: { signal: AbortSignal }): Promise<string>
```






**Swift**



```swift
func listToolsJson() async throws -> String
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun listToolsJson(): String
```






**Rust**



```rust
pub async fn list_tools_json(&self) -> Result<String, CuaError>
```






**Returns** `String` · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.relay_register`

Publishes `space` on the cua.ai relay as a machine of the signed-in
account, the way `cua host setup` publishes this computer: the
Space's own driver dials out, so the account's other devices (a
phone off this network) reach it as `relay:<machine>`, and nobody
else until it is shared. Idempotent.




**Python**



```python
async def relay_register(self, space: str) -> SpaceRelayRegistration
```






**TypeScript**



```ts
relayRegister(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceRelayRegistration>
```






**Swift**



```swift
func relayRegister(space: String) async throws -> SpaceRelayRegistration
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun relayRegister(space: String): SpaceRelayRegistration
```






**Rust**



```rust
pub async fn relay_register(&self, space: String) -> Result<SpaceRelayRegistration, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** [`SpaceRelayRegistration`](</docs/cua-sdk/reference/spaces/space#spacerelayregistration-record>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.relay_unregister`

Takes `space` off the relay (its driver leaves; every share goes).
Returns false when it was not on the relay.




**Python**



```python
async def relay_unregister(self, space: str) -> bool
```






**TypeScript**



```ts
relayUnregister(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<boolean>
```






**Swift**



```swift
func relayUnregister(space: String) async throws -> Bool
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun relayUnregister(space: String): Boolean
```






**Rust**



```rust
pub async fn relay_unregister(&self, space: String) -> Result<bool, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** `bool` · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.remove`

Unregisters a Space (the sandbox is not touched).




**Python**



```python
async def remove(self, space: str) -> None
```






**TypeScript**



```ts
remove(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<void>
```






**Swift**



```swift
func remove(space: String) async throws
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun remove(space: String)
```






**Rust**



```rust
pub async fn remove(&self, space: String) -> Result<(), CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.resolve`

Resolves an id, legacy id, URL or display name.




**Python**



```python
async def resolve(self, space: str) -> SpaceInfo
```






**TypeScript**



```ts
resolve(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceInfo>
```






**Swift**



```swift
func resolve(space: String) async throws -> SpaceInfo
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun resolve(space: String): SpaceInfo
```






**Rust**



```rust
pub async fn resolve(&self, space: String) -> Result<SpaceInfo, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** [`SpaceInfo`](#spaceinfo-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.space`

A connected handle to a registered Space.




**Python**



```python
async def space(self, space: str) -> Space
```






**TypeScript**



```ts
space(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceLike>
```






**Swift**



```swift
func space(space: String) async throws -> Space
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun space(space: String): Space
```






**Rust**



```rust
pub async fn space(&self, space: String) -> Result<Arc<Space>, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** [`Space`](</docs/cua-sdk/reference/spaces/space#space>) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.start`

Turns a Space on again: resumes a suspended one, boots a stopped one
(a Space one of your machines provides joins the relay again), and
leaves a running one as it is. Returns once it answers (bounded).




**Python**



```python
async def start(self, space: str) -> SpacePowerReport
```






**TypeScript**



```ts
start(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<SpacePowerReport>
```






**Swift**



```swift
func start(space: String) async throws -> SpacePowerReport
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun start(space: String): SpacePowerReport
```






**Rust**



```rust
pub async fn start(&self, space: String) -> Result<SpacePowerReport, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** [`SpacePowerReport`](#spacepowerreport-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.stop`

Turns a Space off the way its provider can (`SpaceInfo.power`):
suspends it, keeping its memory (a local container or QEMU VM), or
stops it, keeping its disk (a local Lume VM; a Space one of your
machines provides, which that machine stops). A cloud Space, a Space
added by address and your own computers cannot be turned off.




**Python**



```python
async def stop(self, space: str) -> SpacePowerReport
```






**TypeScript**



```ts
stop(space: string, asyncOpts_?: { signal: AbortSignal }): Promise<SpacePowerReport>
```






**Swift**



```swift
func stop(space: String) async throws -> SpacePowerReport
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun stop(space: String): SpacePowerReport
```






**Rust**



```rust
pub async fn stop(&self, space: String) -> Result<SpacePowerReport, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `space` | `String` | required |

**Returns** [`SpacePowerReport`](#spacepowerreport-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

## `SpaceInfo` record

A registered Space.

Returned by [`Space.info`](</docs/cua-sdk/reference/spaces/space#space>), [`Spaces.add`](#spacesadd), [`Spaces.add_with_service`](#spacesadd_with_service), [`Spaces.list`](#spaceslist), [`Spaces.resolve`](#spacesresolve).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `String` |  | Id, for example `direct:10.0.0.5:3211` or `cloud:<name>` (the sandbox ref scheme). |
| `name` | `String` |  | Display name. |
| `provider` | `String` |  | `cloud`, `local`, `direct` or `relay` (the location words). |
| `spacesd_version` / `spacesdVersion` | `String` |  | spacesd version at the last handshake. |
| `features` | `Vec<String>` |  | Supported features at the last handshake. |
| `os` | `String` |  | Guest OS family at the last handshake: `linux`, `macos`, `windows`, or empty when not reported. |
| `os_name` / `osName` | `String` |  | Guest OS product or distribution at the last handshake ("Ubuntu", "macOS"), or empty when not reported. |
| `os_pretty_name` / `osPrettyName` | `String` |  | The guest's full OS string at the last handshake ("Ubuntu 24.04.3 LTS", "macOS 26.5.2 (25F84)"), or empty from older drivers. |
| `image` | `String` |  | The image the sandbox runs ("ghcr.io/trycua/linux:24.04"), or empty when unknown (a Space added by address). |
| `image_digest` / `imageDigest` | `String` |  | The digest of the variant that runs ("sha256:..."), or empty. |
| `kind` | `String` |  | `container` or `vm`, or empty when unknown. |
| `arch` | `String` |  | The guest's CPU architecture (`arm64`, `amd64`), or empty when unknown. |
| `services` | `Vec<String>` |  | Declared services (never `env`), reachable with `list_tools` / `call_tool` (`service`). A Space without cua-spacesd has an empty `features` list and only these. |
| `added_at` / `addedAt` | `Option<String>` |  | When it was added (RFC 3339). |
| `host` | `String` |  | For a Space one of your machines provides (created with `on="host:<machine>"`): that host's relay machine id; empty otherwise. Lists group these Spaces under their host. |
| `host_name` / `hostName` | `String` |  | The host's display name, when known. |
| `power` | `String` |  | How it turns off and on again (`Spaces.stop`, `Spaces.start`): `suspend` (its memory is kept), `stop` (its disk is kept), or empty when it cannot (a cloud Space, a Space added by address). |
| `power_state` / `powerState` | `String` |  | `running`, `suspended` or `stopped` as cua last recorded it; empty when unknown (a Space one of your machines provides answers while it runs). |
| `cloud` | `String` |  | A Space in your own cloud: the provider (`aws`, `gcp`, `modal`); empty otherwise. |
| `cloud_place` / `cloudPlace` | `String` |  | Where it runs ("AWS · us-west-2"). |
| `cloud_delete` / `cloudDelete` | `String` |  | How `delete` would delete it permanently from here: `here` (this device created it), `host:<machine>` (the device that created it, through the relay) or `elsewhere` (only there; `remove` keeps it). Empty for other Spaces. |

## `SpacePowerReport` record

What `Spaces.stop` or `Spaces.start` did.

Returned by [`Spaces.start`](#spacesstart), [`Spaces.stop`](#spacesstop).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `space` | `String` |  | The Space. |
| `state` | `String` |  | `running`, `suspended` or `stopped`: the state it is in now. |
| `power` | `String` |  | How it turns off: `suspend` (its memory is kept) or `stop` (its disk is kept). |
| `message` | `String` |  | What happened, for people. |

## `spaces_tool_methods`

Which SDK method covers each Spaces contract tool. Language test suites
check every listed method exists on the generated class.




**Python**



```python
def spaces_tool_methods() -> List[SpacesToolMethod]
```






**TypeScript**



```ts
function spacesToolMethods(): Array<SpacesToolMethod>
```






**Swift**



```swift
func spacesToolMethods() -> [SpacesToolMethod]
```






**Kotlin**



```kotlin
fun spacesToolMethods(): List<SpacesToolMethod>
```






**Rust**



```rust
pub fn spaces_tool_methods() -> Vec<SpacesToolMethod>
```






**Returns** [`Vec<SpacesToolMethod>`](#spacestoolmethod-record)

## `SpacesToolMethod` record

One row of `SPACES_TOOL_METHODS`.

Returned by [`spaces_tool_methods`](#spaces_tool_methods).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `tool` | `String` |  | Contract tool name. |
| `method` | `String` |  | `Class.method` (Rust / Python spelling; camelCase in TS, Swift and Kotlin). |