Spaces

The Spaces registry: create, add, resolve, delete and remove Spaces, their create options, and agent runs in a Space.

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. See resize to change a local VM's shape.

`Spaces`#

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

Returned by Cua.spaces.

Method	Description
`add`	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`	`Spaces.add`, naming the service a plain MCP endpoint is registered under (default `mcp`).
`call_tool_json`	Calls any Spaces MCP tool with JSON arguments (the implementation `cua daemon mcp` serves).
`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.
`create`	Creates a Space where `options.on` says (the user default when unset): a new sandbox registered as a Space.
`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.
`delete`	Deletes a Space's sandbox and forgets it (a Space added by address is only forgotten).
`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.
`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>"`.
`list`	Registered Spaces.
`list_known`	The Spaces known now: this machine's at once, and the account's other computers as far as they answered within a moment (`SpaceList` says how far the read got).
`list_tools_json`	The Spaces MCP `tools/list` result as JSON (the contract).
`network_log`	What a Space on the daemon's computer tried to reach and its network refused, most recent first (`cua network log`).
`remove`	Unregisters a Space (the sandbox is not touched).
`rename`	Gives a Space a new name; its id stays the same.
`resolve`	Resolves an id, legacy id, URL or display name.
`set_clipboard`
`set_volume`	Sets when a Space's viewers may move the clipboard between this computer and the Space: `viewing` (only while you're viewing, the default), `ask` or `off`.
`space`	A connected handle to a registered Space.
`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.
`stop`	Turns a Space off the way its provider can (`SpaceInfo.power`): stops it, keeping its disk and freeing its memory (a local VM; a Space one of your machines provides, which that machine stops), or suspends it, keeping its memory (a local container that cannot stop). `Spaces.suspend` suspends a local container or QEMU VM on purpose.
`suspend`	Suspends a local Space (a container or a QEMU VM), keeping its memory: it resumes where it was, and its memory stays in use until then. `Spaces.stop` stops it instead and frees its memory.
`ack_network_notice`	Marks the one-time notice about the new network defaults as shown for `space` (`SpaceNetworkInfo.notice_pending`).
`agent_capabilities`	What every agent harness is and cannot do (`agent_capabilities`), as JSON.
`agent_pause`	Pauses a persistent agent: run, routines and (local) Space.
`agent_resume`	Resumes a paused persistent agent; with `prompt`, starts a run.
`build`	Builds an image from a Dockerfile or steps in a Space, as pinned layer checkpoints on this machine.
`build_with_progress`	`Spaces.build`, reporting each step and the lines it prints to `listener` as they happen.
`builds`	The builds on this machine, oldest first, with their tags.
`cloud_add_host`	Adds `count` hosts of `instance_type` in a linked cloud by hand (the scaler never removes them); each ends at its TTL.
`cloud_approve`	Approves what an agent asked for on `provider` (its link, or a raise of its limits), or with `deny` declines it.
`cloud_audit`	What Cua did in your clouds, newest last (default the newest 50).
`cloud_budget`	The elastic pool's budget and autoscale switch, after setting the fields `update` gives.
`cloud_connect`	Connects a cloud account (after the checks `cloud_test` runs).
`cloud_cost`	What the machines Cua created cost (an estimate: list price times runtime), grouped `by` `space`, `agent`, `day` or `cloud`, since `since` (`YYYY-MM-DD`; default the first of this month), for one `provider` or every cloud.
`cloud_disconnect`	Forgets a connected cloud.
`cloud_hosts`	The hosts the elastic pool added in your clouds, with their cost.
`cloud_plan`	What the elastic pool would do for some Spaces: where each goes (your devices first, then hosts with room, then new cloud machines at the least cost) and what that costs.
`cloud_reconcile`	One scale-in pass now: idle hosts go at the end of their paid time, the least-used one is cordoned when the others have room.
`cloud_remove_host`	Removes hosts this home added to the pool.
`cloud_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`	What Cua left in your clouds (expired Spaces, resources whose Space is gone; with `all`, everything Cua created there).
`cloud_test`	Checks a cloud account without creating anything.
`computer_access`	Per-agent computer grants (of one agent, or all).
`computer_access_grant`	Lets one persistent agent use one of the user's computers (asks for presence).
`computer_access_revoke`	Takes a persistent agent's computer access back (every machine when `machine` is empty).
`create_volume`	Creates the empty named volume `name` (1 to 63 of `a-z`, `0-9`, `.`, `_`, `-`).
`delete_build`	Deletes a build: its tags and the layer checkpoints no other build uses.
`delete_many`	Deletes several Spaces (`Spaces.delete` each), at most three at a time, turning running ones off first.
`delete_tree`	`Spaces.delete`, with `keep_children`: its child Spaces become top-level Spaces and keep running instead of being deleted first.
`delete_volume`	Deletes the named volume `name` and its files (their history stays in the Cua Volume).
`fork`	Starts Space `name` from `source` (a Space id such as `local:<name>`, a sandbox name, a checkpoint name, or the tag of a build (`Spaces.build`) or its checkpoint; a sandbox wins) and returns it connected.
`leave_many`	Takes this account off Spaces shared with it (through the relay): a direct share ends, a team's Space leaves this account's list.
`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.
`network`	A Space's network: its settings, what they open, where they are enforced (or why its network is cut), and what is always blocked.
`notifications`	The notifications feed, newest first.
`notifications_ack`	Marks notifications read (every one when `ids` is empty).
`notify_user`	Posts a notification to the Cua app.
`orphans`	Child Spaces whose parent is gone or out of reach.
`persistent_agent_create`	Creates a persistent agent: `harness` working in `space`, its home at `agents/<name>/` in the Cua Volume.
`persistent_agent_remove`	Forgets a persistent agent (its home stays in the drive).
`persistent_agent_save`	Saves a persistent agent's home into the drive now.
`persistent_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`	Every persistent agent.
`prewarm`	Keeps Spaces of `image` ready where the elastic pool puts them (the same solve as `on` `auto`, under the budget and pins), so the next creates of that shape start in a fraction of a second.
`prewarms`	The prewarms, with how many each keeps ready now.
`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.
`relay_unregister`	Takes `space` off the relay (its driver leaves; every share goes).
`relay_unregister_computer`	`Spaces.relay_unregister` for one of your computers (`relay:<machine>`), choosing what happens to the Spaces it provides: with `delete_spaces` false they stay on the account, detached (they come back when the computer registers again); with true they are deleted too, files first (through the computer while it answers), then their records.
`remove_prewarm`	Ends prewarm `id` (its ready Spaces go).
`resize`	Gives a local VM Space another shape: `cpus` vCPUs, `memory_mb` MiB of memory, a disk grown to `disk_gb` GiB (each `None` keeps it).
`resources`	What this Mac, its extra Spaces and your other computers use now: processor, memory and disk, as one snapshot (a few seconds old at most).
`routine_add`	Adds a routine.
`routine_remove`	Deletes a routine.
`routine_set_enabled`	Turns a routine on or off.
`routines`	Routines (of one agent, or all).
`set_children`	Lets a Space make child Spaces of its own, or stops it.
`set_egress`	Replaces a Space's egress policy; an empty one removes it (see `EgressPolicy`).
`set_lifetime`	Gives a Space a lifetime of `seconds` from now, replacing any earlier one: when it passes, the cua daemon deletes the Space (`on_expire` `"delete"`, the default) or turns it off (`"suspend"`), whether or not this process is still running.
`set_network`	Replaces a Space's network settings (see `NetworkSettings`).
`set_tree_budget`	Sets the budget of `space`'s tree: how many child Spaces, vCPUs and memory its children may hold at once, and what they may cost.
`tree_budget`	The budget of `space`'s tree (any Space of it) and what its children use now.
`volume_approve`	`volume_approve`: the request becomes a grant (with presence).
`volume_audit`	`volume_audit`: the newest events (default 50) and whether the log verified.
`volume_cache_clear`	`volume_cache_clear`: drops every cached block.
`volume_cache_set`	`volume_cache_set`: the cache's size cap (at least 256 MiB).
`volume_cache_stats`	`volume_cache_stats`: the block cache's size, cap and hit rate.
`volume_delete`	`volume_delete`: a delete marker (history stays).
`volume_deny`	`volume_deny`.
`volume_grant`	`volume_grant`: widens `principal`'s access (`agent:<name>` or `space:<id>`, mode `r` or `rw`).
`volume_grants`	`volume_grants`: live grants (every grant with `all`).
`volume_history`	`volume_history`: a file's versions, newest first.
`volume_ls`	`volume_ls`: a folder's immediate children (default the root).
`volume_mount`	`volume_mount`: turns the mount on (kept across restarts) and mounts.
`volume_mount_status`	`volume_mount_status`: whether the drive is mounted as a volume.
`volume_read`	`volume_read`: a file (or one of its versions).
`volume_request_access`	`volume_request_access`: `agent` asks the user for more access.
`volume_requests`	`volume_requests`: requests waiting for the user.
`volume_restore`	`volume_restore`: makes an old version current again.
`volume_revoke`	`volume_revoke`.
`volume_storage`	`volume_storage`: where the drive keeps its bytes.
`volume_storage_set`	`volume_storage_set`: tests, and unless `dry_run` saves and switches to, a storage backend (live, no restart).
`volume_sync_events`	`volume_sync_events`: events after `since_seq`, waiting up to `wait_ms` (at most 30000) for one.
`volume_sync_resolve`	`volume_sync_resolve`: clears a conflict from the list (files stay).
`volume_sync_status`	`volume_sync_status`: devices, pending uploads and conflicts.
`volume_unmount`	`volume_unmount`: turns the mount off; pending uploads land first.
`volume_write`	`volume_write`: a new version of a file.
`volumes`	The named volumes of Cua Volume, by name, with the Spaces that mount each.
`watch_list`	Tells `listener` when the Space list changed: once at the start, then on every change.
`watch_resources`	The same numbers as events for `listener`: a snapshot first, then an update with only the entries that changed by more than 1 point or 256 MB, and `LowDisk` whenever the warning level changes.

`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

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

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 computer 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

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

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

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

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 relay registration) and what the create made is removed (its VM or container and disks, 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

Parameter	Type	Default
`space`	`String`	required

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

Parameter	Type	Default
`options`	`SpaceCreateOptions`	required

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

Parameter	Type	Default
`options`	`SpaceCreateOptions`	required
`listener`	`SpaceCreateListener`	required

Returns SpaceCreateResult · Async · Raises CuaError

`Spaces.delete`#

Deletes a Space's sandbox and forgets it (a Space added by address is only forgotten). Its child Spaces are deleted first. Returns what happened.

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

Parameter	Type	Default
`space`	`String`	required

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]

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

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

The Spaces known now: this machine's at once, and the account's other computers as far as they answered within a moment (SpaceList says how far the read got). A slow or unreachable relay never holds up or fails this machine's own Spaces, so an app shows them right away and reads again while the list is incomplete. Spaces.list waits for every computer instead.

async def list_known(self) -> SpaceList

Returns SpaceList · 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.network_log`#

What a Space on the daemon's computer tried to reach and its network refused, most recent first (cua network log).

async def network_log(self, space: str) -> List[NetworkEvent]

Parameter	Type	Default
`space`	`String`	required

Returns Vec<NetworkEvent> · Async · Raises CuaError

`Spaces.remove`#

Unregisters a Space (the sandbox is not touched).

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

Parameter	Type	Default
`space`	`String`	required

Async · Raises CuaError

`Spaces.rename`#

Gives a Space a new name; its id stays the same. Returns the Space as it is listed now (display_name, or name for a Space that is a machine on the relay).

The name follows the rule a create's does (lowercase letters, digits and dashes, starting and ending with a letter or digit, at most 63) and may not be another of your Spaces' names (InvalidArgument). Only its owner renames a Space: one shared with you is refused (PermissionDenied). A Space you shared, or one of your computers provides, is renamed on the relay too, so your other devices and the people it is shared with see the new name.

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

Parameter	Type	Default
`space`	`String`	required
`name`	`String`	required

Returns SpaceInfo · Async · Raises CuaError (InvalidArgument, PermissionDenied)

`Spaces.resolve`#

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

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

Parameter	Type	Default
`space`	`String`	required

Returns SpaceInfo · Async · Raises CuaError

`Spaces.set_clipboard`#

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

Parameter	Type	Default
`space`	`String`	required
`clipboard`	`String`	required

Async · Raises CuaError

`Spaces.set_volume`#

Sets when a Space's viewers may move the clipboard between this computer and the Space: viewing (only while you're viewing, the default), ask or off. It applies to viewers opened afterwards. The agent tools computer_clipboard_* act inside the Space and are not affected. Another word is InvalidArgument. Sets what a Space sees of the Cua Volume: own (its own folder) or off. Applies now: off unmounts the Volume (named volumes it mounted stay).

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

Parameter	Type	Default
`space`	`String`	required
`volume`	`String`	required

Async · Raises CuaError (InvalidArgument)

`Spaces.space`#

A connected handle to a registered Space.

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

Parameter	Type	Default
`space`	`String`	required

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

Parameter	Type	Default
`space`	`String`	required

Returns SpacePowerReport · Async · Raises CuaError

`Spaces.stop`#

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

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

Parameter	Type	Default
`space`	`String`	required

Returns SpacePowerReport · Async · Raises CuaError

`Spaces.suspend`#

Suspends a local Space (a container or a QEMU VM), keeping its memory: it resumes where it was, and its memory stays in use until then. Spaces.stop stops it instead and frees its memory.

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

Parameter	Type	Default
`space`	`String`	required

Returns SpacePowerReport · Async · Raises CuaError

Create options#

Spaces.create takes SpaceCreateOptions (with an EgressPolicy for the destinations a Linux Space may reach) and returns a SpaceCreateResult. A SpaceCreateListener receives SpaceCreateProgress while it runs; Spaces.cancel_create stops it. GpuSupport says whether a location offers GPU acceleration.

`SpaceCreateOptions` record#

Options for Spaces.create: the same location / kind / runtime model as sandboxes.

Field	Type	Default	Description
`image`	`Option<String>`	`None`	Image (default: the canonical Linux image). `checkpoint:<name>` starts a fork of that checkpoint, on whichever of your machines holds it (`CheckpointSummary.host`): its disk, memory and processes, so no command, environment, services, GPU or disk size.
`on`	`Option<String>`	`None`	Where: `local` (free), a connected cloud account (`aws`, `gcp`, `modal`) or `host:<name>`. `None`: the user default (`default.on`, `CUA_DEFAULT_ON`, else `local`); for a `checkpoint:` image, where the checkpoint is. A checkpoint also starts on `host:<machine>` or `auto`, copied there first when that machine lacks it.
`kind`	`Option<String>`	`None`	`auto` (default), `container`, `vm` or `microvm`.
`runtime`	`Option<String>`	`None`	`auto` (default) or an engine the location offers for the kind.
`name`	`Option<String>`	`None`	Name (default `space-<hex>`).
`cpus`	`Option<u32>`	`None`	vCPUs. Local default 2.
`memory_mb` / `memoryMb`	`Option<u64>`	`None`	Memory in MiB. Local default 4096.
`disk_gb` / `diskGb`	`Option<u32>`	`None`	Grow the VM's disk to this many GiB (local VMs; default: the image's size, never smaller). Lume grows the macOS APFS container before the first boot; Linux images grow their root partition at boot. Containers and cloud Spaces refuse it.
`timeout_ms` / `timeoutMs`	`Option<u64>`	`None`	Readiness budget (local; default 600 s).
`wait`	`Option<bool>`	`None`	Wait until ready (default true).
`reuse`	`bool`	`false`	Return a reachable registered Space in the same location with the requested services instead of creating one.
`command`	`Option<Vec<String>>`	`None`	Entrypoint override.
`env`	`HashMap<String, String>`	`[:]`	Guest environment.
`services`	`HashMap<String, u16>`	`[:]`	Named services (name → guest port), for example `{"mcp": 8765}`.
`spacesd`	`Option<bool>`	`None`	Whether the image runs cua-spacesd (default: yes for the canonical images; any other image gets a static one injected on a local container or microVM, so it is a full Space; `false` runs the image as it is).
`gpu`	`Option<String>`	`None`	A GPU option of the runtime the Space runs on (`Spaces.gpu_support`): `paravirtual` for a macOS VM on Lume (GPU acceleration, experimental), `virgl` (QEMU on Linux), `nvidia` (a runc container on Linux); `auto` picks the runtime's own. `None` (the default): no GPU. Kept with the Space.
`create_id` / `createId`	`Option<String>`	`None`	Your own key for this create (an app's pending row), for `Spaces.cancel_create` before the Space's id is known.
`durable`	`bool`	`false`	Keep the Space on your machines (`on` "auto"): when its machine goes away it is created again on another one, with the same name (its disk starts fresh). Needs the cua daemon of Cua Spaces and an account with machines that provide Spaces.
`profile`	`Option<String>`	`None`	A size profile: defaults for what is left unset. `"rollout"`: 1 vCPU, 1024 MiB and `headless` (a local VM gets no display hardware, so many more fit on one machine), for RL rollouts and agent episodes that mostly wait. `None` or `"default"`: 2 vCPUs, 4096 MiB.
`headless`	`Option<bool>`	`None`	A Space without a desktop: only cua-spacesd runs (exec, files, processes, MCP), with no display, window manager or audio. For shell and RL workloads it starts several times faster and fits many more per machine. `None`: what `profile` says (a desktop by default).
`forkable`	`Option<bool>`	`None`	A fork source (a "bake" Space): a local QEMU VM's guest RAM is a shared file, so its checkpoints (`Space.checkpoint`) take milliseconds and forks of them (`Space.fork`, `Spaces.fork`) share its pages. Other kinds ignore it. `None` (the default): not one.
`build`	`Option<BuildOptions>`	`None`	Build an image first (cached when unchanged), then fork the result. `image` must be unset.
`volumes`	`Vec<VolumeMount>`	`[]`	Named volumes of Cua Volume to mount in the Space (`Spaces.create_volume`): each appears at its `path`, read-write or read-only; the Space sees no other volume. Needs the Cua Volume (Cua Spaces) and a guest that can mount it; the create fails otherwise, naming what is missing. A fork mounts the same volumes.
`network`	`Option<String>`	`None`	Guest network: `default` (unset) gives outbound network; `none` gives none (QEMU VMs, here or on one of your machines; published ports and cua-spacesd still reach the guest). Not with `durable` or `reuse`. A daemon or machine whose cua is too old to enforce `none` is refused (`CapabilityMissing`) and the Space it made is deleted.
`labels`	`HashMap<String, String>`	`[:]`	Labels kept with the Space and returned in `SpaceInfo.labels`: at most 64; keys and values are not empty (UTF-8); keys up to 63 bytes, values up to 256. Not with `durable` or `reuse`. The device that creates the Space keeps them (also for `host:` and `auto`).
`egress`	`Option<EgressPolicy>`	`None`	Egress policy (see `EgressPolicy`), enforced by the host the Space runs on from the guest's first instruction. A kind or location with no host-side point refuses it (`Unsupported`) before anything is created. Not with `durable`, `reuse` or `wait = false`; a daemon too old to enforce it makes the create fail.
`network_settings` / `networkSettings`	`Option<NetworkSettings>`	`None`	Network settings (see `NetworkSettings`). `None`: what `network` and `egress` say (`internet` when neither says anything). A daemon too old to keep them makes the create fail.
`parent`	`Option<String>`	`None`	Create it as a child of this Space (id or name): its network is no more open than its parent's, and it joins the parent's tree.
`widen`	`Option<bool>`	`None`	With `parent`: let its network be more open than its parent's (recorded on the Space).
`instance_type` / `instanceType`	`Option<String>`	`None`	With `on` a linked cloud (`aws`, `hetzner`, ...): the machine type its host must be (`c7g.xlarge`, `cax41`), a pin of the elastic pool's solve. `None`: the pool picks the cheapest that fits.
`region`	`Option<String>`	`None`	With `on` a linked cloud: the region its host must be in.
`children`	`Option<bool>`	`None`	Lets the Space make child Spaces of its own (`Spaces.set_children`). `None`: off. Only a Space the machine of the runtime runs itself.

`EgressPolicy` record#

Which destinations a Space may open connections to. Everything is allowed unless a rule says otherwise: every deny entry blocks that destination, every allow entry is an exception that wins over deny (deny: ["all"] with allow: ["1.1.1.1"] leaves only 1.1.1.1 reachable), and an allow list with no deny blocks nothing. Entries are IPv4/IPv6 addresses or CIDRs (all is 0.0.0.0/0 and ::/0); a hostname is refused (rules are by IP/CIDR). DNS works only while the resolver the guest uses is not blocked (or is allowed): there is no special case. Loopback, replies to connections made to the guest and IPv6 neighbor discovery are never filtered.

The host the Space runs on enforces it, outside the guest, from the guest's first instruction (SpaceInfo.egress_enforced): containers (runc and gVisor) on the container engine's host, Firecracker and QEMU VMs on Linux in a network namespace around the VM. Nothing in the guest, root included, can change it. macOS VMs, Apple Containerization, QEMU on macOS or Windows, Cua Cloud and your own cloud accounts refuse a policy (Unsupported, saying why).

Field	Type	Default	Description
`allow`	`Vec<String>`	`[]`	Destinations that stay reachable where `deny` blocks them.
`deny`	`Vec<String>`	`[]`	Destinations that are blocked.

`SpaceCreateResult` record#

Result of Spaces.create.

Returned by Spaces.create, Spaces.create_with_progress.

Field	Type	Description
`space`	`Option<SpaceInfo>`	The Space, once ready.
`pending_id` / `pendingId`	`Option<String>`	With `wait = false`: the id the Space will have.
`reused`	`bool`	`reuse` returned an existing Space.

`SpaceCreateProgress` record#

What a Space create is doing (see Spaces.create_with_progress).

Field	Type	Default	Description
`phase`	`String`		`preparing`, `pulling`, `creating`, `booting`, `waiting_for_services`, `connecting` or `ready`, in that order.
`fraction`	`Option<f64>`		How far through the phase, 0.0 to 1.0, when its size is known (an image pull).
`detail`	`String`		One short line, for example the image being pulled.
`bytes_done` / `bytesDone`	`Option<u64>`	`None`	Bytes downloaded so far, when the step counts them (an image pull).
`bytes_total` / `bytesTotal`	`Option<u64>`	`None`	Bytes the download has in all.
`bytes_per_second` / `bytesPerSecond`	`Option<f64>`	`None`	Smoothed download rate, bytes per second (time left: the bytes to go over it).
`space`	`String`	`""`	The id the Space will have (`local:<name>`), for `Spaces.cancel_create`.

`SpaceCreateListener`#

Receives SpaceCreateProgress while Spaces.create_with_progress runs, in order, ending with ready. Called on an SDK worker thread; return quickly.

You implement SpaceCreateListener and pass it to the SDK (a callback interface): subclass it in Python, implement the interface in TypeScript, the SpaceCreateListener protocol in Swift, the interface in Kotlin and the trait in Rust.

Method	Description
`on_progress`	The create moved on.

`SpaceCreateListener.on_progress`#

The create moved on.

def on_progress(self, progress: SpaceCreateProgress) -> None

Parameter	Type	Default
`progress`	`SpaceCreateProgress`	required

`SpaceCancelOutcome` record#

What Spaces.cancel_create did.

Returned by Spaces.cancel_create.

Field	Type	Description
`id`	`String`	The Space id the create had (`local:<name>`), when known.
`state`	`String`	`cancelled`, `not_creating` (nothing by that key is running) or `already_created` (it finished: delete it instead).
`message`	`String`	What was removed and what stays, for people.

`GpuSupport` record#

The GPU options of one runtime: empty, with the reason, when it has none.

Returned by Spaces.gpu_support.

Field	Type	Description
`runtime`	`String`	`lume`, `qemu`, `container`, `gvisor`, a provider's name.
`options`	`Vec<GpuOption>`	Its options.
`reason`	`String`	Why it has none.

`GpuOption` record#

One GPU option of a runtime (see Spaces.gpu_support).

Field	Type	Description
`id`	`String`	What to pass as `gpu`.
`label`	`String`	How a person names it ("GPU acceleration").
`experimental`	`bool`	Experimental.
`supported`	`bool`	Works on this host now.
`reason`	`String`	Why not, one short line (empty when supported).
`learn_more` / `learnMore`	`Option<String>`	A page that explains it.
`usd_per_hour` / `usdPerHour`	`Option<f64>`	Estimated cost per hour while it runs (cloud GPU types).

Spaces

Spaces#

Spaces.add#

Spaces.add_with_service#

Spaces.call_tool_json#

Spaces.cancel_create#

Spaces.create#

Spaces.create_with_progress#

Spaces.delete#

Spaces.gpu_support#

Spaces.hosts#

Spaces.list#

Spaces.list_known#

Spaces.list_tools_json#

Spaces.network_log#

Spaces.remove#

Spaces.rename#

Spaces.resolve#

Spaces.set_clipboard#

Spaces.set_volume#

Spaces.space#

Spaces.start#

Spaces.stop#

Spaces.suspend#

Create options#

SpaceCreateOptions record#

EgressPolicy record#

SpaceCreateResult record#

SpaceCreateProgress record#

SpaceCreateListener#

SpaceCreateListener.on_progress#

SpaceCancelOutcome record#

GpuSupport record#

GpuOption record#

`Spaces`#

`Spaces.add`#

`Spaces.add_with_service`#

`Spaces.call_tool_json`#

`Spaces.cancel_create`#

`Spaces.create`#

`Spaces.create_with_progress`#

`Spaces.delete`#

`Spaces.gpu_support`#

`Spaces.hosts`#

`Spaces.list`#

`Spaces.list_known`#

`Spaces.list_tools_json`#

`Spaces.network_log`#

`Spaces.remove`#

`Spaces.rename`#

`Spaces.resolve`#

`Spaces.set_clipboard`#

`Spaces.set_volume`#

`Spaces.space`#

`Spaces.start`#

`Spaces.stop`#

`Spaces.suspend`#

`SpaceCreateOptions` record#

`EgressPolicy` record#

`SpaceCreateResult` record#

`SpaceCreateProgress` record#

`SpaceCreateListener`#

`SpaceCreateListener.on_progress`#

`SpaceCancelOutcome` record#

`GpuSupport` record#

`GpuOption` record#