Local runtimes
The container and VM runtimes this machine can host, their setup, and local images.
The container and VM runtimes this machine can host, their setup, and local images.
cua.local() checks and sets up the local runtimes and moves images in and out of the local engines.
Python programs usually use the high-level API instead: cua_sandbox runtimes.
Local#Local runtimes and images.
Returned by Cua.local.
| Method | Description |
|---|---|
build_image | Builds an image from an images.cua.ai/v1alpha1 Image resource (JSON) on base; pushes to push when set. |
doctor | Inspects local runtimes (read-only: never installs or starts anything). |
pull_image | Pulls an image (container engine for container refs, the image cache for vm: containerDisks). |
push_image | Copies an image (host architecture) to destination; returns the pushed manifest digest. |
setup | Provisions components (qemu, lume; runsc reports its plan). |
storage | Free space where local Spaces are written (Lume's VM storage, the cua home for QEMU, the container engine's data disk) and which catalog images are already pulled. |
Local.build_image#Builds an image from an images.cua.ai/v1alpha1 Image resource
(JSON) on base; pushes to push when set. Returns
reference@digest or the local output directory.
async def build_image(self, spec_json: str, base: str, push: Optional[str]) -> str| Parameter | Type | Default |
|---|---|---|
spec_json | String | required |
base | String | required |
push | Option<String> | required |
Returns String · Async · Raises CuaError
Local.doctor#Inspects local runtimes (read-only: never installs or starts anything).
async def doctor(self) -> DoctorReportReturns DoctorReport · Async · Raises CuaError
Example
import asyncio
import cua
async def main():
report = await cua.embedded().local().doctor()
for check in report.checks:
print(check.name, check.status)
asyncio.run(main())Local.pull_image#Pulls an image (container engine for container refs, the image cache
for vm: containerDisks).
async def pull_image(self, reference: str) -> LocalImage| Parameter | Type | Default |
|---|---|---|
reference | String | required |
Returns LocalImage · Async · Raises CuaError
Local.push_image#Copies an image (host architecture) to destination; returns the
pushed manifest digest.
async def push_image(self, reference: str, destination: str) -> str| Parameter | Type | Default |
|---|---|---|
reference | String | required |
destination | String | required |
Returns String · Async · Raises CuaError
Local.setup#Provisions components (qemu, lume; runsc reports its plan).
Empty = everything provisionable. dry_run only reports.
async def setup(self, components: List[str], dry_run: bool) -> List[SetupStep]| Parameter | Type | Default |
|---|---|---|
components | Vec<String> | required |
dry_run | bool | required |
Returns Vec<SetupStep> · Async · Raises CuaError
Local.storage#Free space where local Spaces are written (Lume's VM storage, the cua home for QEMU, the container engine's data disk) and which catalog images are already pulled. Read-only and bounded; probed in this process (the daemon runs on the same host).
async def storage(self) -> LocalStorageReturns LocalStorage · Async · Raises CuaError
DoctorReport record#Doctor output.
Returned by Local.doctor.
| Field | Type | Default | Description |
|---|---|---|---|
checks | Vec<RuntimeCheck> | One check per backend. | |
report_json / reportJson | String | The full cua-vmm host report as JSON. |
LocalImage record#A local image.
Returned by Local.pull_image.
| Field | Type | Default | Description |
|---|---|---|---|
reference | String | Reference. | |
kind | String | container or vm. | |
location | String | Disk path (VM) or engine image reference (container). | |
size_bytes / sizeBytes | u64 | Size in bytes, when known. |
LocalStorage record#What local Spaces have room for (see Local.storage).
Returned by Local.storage.
| Field | Type | Default | Description |
|---|---|---|---|
host_arch / hostArch | String | This host's architecture (arm64, amd64). | |
reserve_bytes / reserveBytes | u64 | Bytes cua keeps free on a volume: a create that would leave less fails (CUA_DISK_MIN_FREE, default 5 GiB). | |
lume | Option<StorageVolume> | Where Lume writes macOS VMs. | |
qemu | Option<StorageVolume> | Where QEMU writes VM disks and the containerDisk cache. | |
container | Option<StorageVolume> | The container engine's data disk (Colima, Docker Desktop, OrbStack, /var/lib/docker), when its free space can be read. | |
pulled | Vec<String> | Catalog image refs already pulled here at their published digest. |
RuntimeCheck record#One doctor check (one backend).
| Field | Type | Default | Description |
|---|---|---|---|
name | String | Backend (container, qemu, lume, ...). | |
status | RuntimeCheckStatus | Status. | |
version | Option<String> | Version, when detected. | |
detail | String | Explanation, missing pieces and what setup would do. |
SetupStep record#One setup step.
Returned by Local.setup.
| Field | Type | Default | Description |
|---|---|---|---|
name | String | Component. | |
status | RuntimeCheckStatus | Status after the step. | |
detail | String | What was (or would be) done. |
StorageVolume record#Space on the volume a local engine writes to.
| Field | Type | Default | Description |
|---|---|---|---|
available_bytes / availableBytes | u64 | Bytes available to this user. | |
total_bytes / totalBytes | u64 | Volume size in bytes. | |
name | String | What a person calls it: Macintosh HD, Colima, Docker Desktop. |
RuntimeCheckStatus enum#Status of one local runtime component.
RuntimeCheckStatus.OK
RuntimeCheckStatus.INSTALLABLE
RuntimeCheckStatus.ERROR
RuntimeCheckStatus.NOT_APPLICABLE
RuntimeCheckStatus.UNKNOWN| Variant | Description |
|---|---|
Ok | Present and usable. |
Installable | Missing; setup can provision it. |
Error | Missing or broken; needs user action. |
NotApplicable | Not used on this host. |
Unknown | Not reported. |