Spaces

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.

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.

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.

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

Returns SpaceInfo · Async · Raises CuaError

Example

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())

Spaces.add_with_service#

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

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

Returns SpaceInfo · Async · Raises CuaError

Spaces.call_tool_json#

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

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

Returns SpaceToolResult · Async · Raises CuaError

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.

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

Returns SpaceCancelOutcome · Async · Raises CuaError (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.

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

Returns SpaceCreateResult · Async · Raises CuaError

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.

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

Returns SpaceCreateResult · Async · Raises CuaError

Spaces.delete#

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

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

Returns String · Async · Raises CuaError

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.

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

Returns Vec<GpuSupport> · Async · Raises CuaError

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.

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

Returns Vec<SpacesHost> · Async · Raises CuaError

Spaces.list#

Registered Spaces.

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

Returns Vec<SpaceInfo> · Async · Raises CuaError

Spaces.list_tools_json#

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

async def list_tools_json(self) -> str

Returns String · Async · Raises CuaError

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.

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

Returns SpaceRelayRegistration · Async · Raises CuaError

Spaces.relay_unregister#

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

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

Returns bool · Async · Raises CuaError

Spaces.remove#

Unregisters a Space (the sandbox is not touched).

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

Async · Raises CuaError

Spaces.resolve#

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

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

Returns SpaceInfo · Async · Raises CuaError

Spaces.space#

A connected handle to a registered Space.

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

Returns Space · Async · Raises CuaError

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

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

Returns SpacePowerReport · Async · Raises CuaError

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.

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

Returns SpacePowerReport · Async · Raises CuaError

SpaceInfo record#

A registered Space.

Returned by Space.info, Spaces.add, Spaces.add_with_service, Spaces.list, Spaces.resolve.

SpacePowerReport record#

What Spaces.stop or Spaces.start did.

Returned by Spaces.start, Spaces.stop.

spaces_tool_methods#

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

def spaces_tool_methods() -> List[SpacesToolMethod]

Returns Vec<SpacesToolMethod>

SpacesToolMethod record#

One row of SPACES_TOOL_METHODS.

Returned by spaces_tool_methods.