Create options
What `Spaces.create` takes and reports: options, progress, cancel and GPU acceleration.
What `Spaces.create` takes and reports: options, progress, cancel and GPU acceleration.
Spaces.create takes SpaceCreateOptions 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). |
on | Option<String> | None | Where: local (free) or cloud (metered). None: the user default (default.on, CUA_DEFAULT_ON, else local). |
kind | Option<String> | None | auto (default), container or vm. |
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; cloud 1-64 (most accounts run 1-8; Fleet decides), default the pool template's (4). |
memory_mb / memoryMb | Option<u64> | None | Memory in MiB. Local default 4096; cloud 512 up to 524288 (most accounts run 1024-32768; Fleet decides), default the pool template's (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, no for any other image). |
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. |
SpaceCreateResult record#Result of Spaces.create.
Returned by Spaces.create, Spaces.create_with_progress.
| Field | Type | Default | 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 | Default | 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 | Default | Description |
|---|---|---|---|
runtime | String | lume, qemu, container, gvisor, fleet, 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 | Default | 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). |