Fleet

Cloud pools and templates: apply, check, export, scale and delete (advanced).

cua.fleet() manages cloud capacity directly: named pools, claims and images. Most programs only need Sandboxes.create with on: "cloud", which manages pools for you.

Python programs usually use the high-level API instead: cua_sandbox.Pool.

`Fleet`#

Fleet control plane.

Returned by Cua.fleet.

Method	Description
`apply`	Reconciles pool `name` (= namespace = template) to run `spec` with `options`: the one pool writer (rolls a new pool back if the template fails).
`apply_pool`	Deprecated: use `Fleet.apply`.
`apply_pool_template`	Lays the set fields of `spec` over pool `pool`'s template and writes it (the pool's capacity is kept; a no-op when nothing differs).
`billing_status`	The account's Cua Cloud billing: its credit, card and the website billing page.
`check_pool_spec`	Compares the set fields of `spec` with pool `pool`'s template: `PoolSpecMismatch` (with a readable diff) when they differ.
`delete_pool`	Deletes a pool, its namespace and its same-named template.
`export_pool`	Reads pool `name` back as the shared model, with its `fleets_pool` Terraform block.
`get_pool`	Looks up a pool.
`list_pools`	Lists pools in a namespace.
`list_templates`	Lists templates in a namespace as JSON resources.
`pool_image_info`	The image pool `name`'s template runs, as a claim on it reports it (`Sandbox.image_info`): pinned by the resolver (cached per pool), or the template reference with empty `pinned_ref`/`digest` when the registry cannot be read.
`set_pool_replicas`	Sets warm replicas (0 suspends).
`usage_pricing`	This account's Cua Cloud rates (`GET /api/config`), reused for five minutes.
`wait_pool_ready`	Waits for at least one ready replica.
`acquire`	Claims a sandbox from a pool and waits for it to bind.
`acquire_with`	`Fleet.acquire` with claim options, including a per-claim env token (bounded wait for its delivery; `ClaimSecretsNotDelivered` releases the claim).
`attach_claim`	Waits for a named claim to bind.
`claim`	Creates a claim without waiting.
`create_image`	Creates an image resource (remote build) from a JSON manifest.
`create_signed_service_url`	Mints a signed, shareable service URL.
`delete_image`	Deletes an image resource.
`get_image`	Gets an image resource (JSON).
`keep_alive`	Extends a claim's lease; returns the RFC 3339 shutdown time.
`list_claims`	Lists claims in a namespace.
`list_images`	Lists image resources (JSON) in a namespace.
`release`	Releases a claim (missing claims are fine).
`service_url`	The gateway URL of a sandbox service (needs the Fleet bearer).

Accessor	Returns	Description
`base_url()`	`String`	Fleet API base URL.
`ephemeral_pool_name()`	`String`	A random ephemeral pool name (`cua-eph-<hex>`).
`pools()`	`FleetPools`	Managed pools (list, gc).

`Fleet.apply`#

Reconciles pool name (= namespace = template) to run spec with options: the one pool writer (rolls a new pool back if the template fails). The image is pinned to the variant the runtime runs; spec.registry_secret is written as the pool's pull Secret.

async def apply(self, name: str, spec: SandboxSpec, options: PoolOptions) -> FleetPool

Parameter	Type	Default
`name`	`String`	required
`spec`	`SandboxSpec`	required
`options`	`PoolOptions`	required

Returns FleetPool · Async · Raises CuaError

`Fleet.apply_pool`#

Deprecated: use Fleet.apply. Reconciles a pool and its template from the flat spec (converted to SandboxSpec + PoolOptions).

async def apply_pool(self, spec: FleetPoolSpec) -> FleetPool

Parameter	Type	Default
`spec`	`FleetPoolSpec`	required

Returns FleetPool · Async · Raises CuaError

`Fleet.apply_pool_template`#

Lays the set fields of spec over pool pool's template and writes it (the pool's capacity is kept; a no-op when nothing differs).

async def apply_pool_template(self, pool: str, spec: SandboxSpec) -> None

Parameter	Type	Default
`pool`	`String`	required
`spec`	`SandboxSpec`	required

Async · Raises CuaError

`Fleet.billing_status`#

The account's Cua Cloud billing: its credit, card and the website billing page. A Fleet without billing answers billing_enabled: false.

async def billing_status(self) -> FleetBillingStatus

Returns FleetBillingStatus · Async · Raises CuaError

`Fleet.check_pool_spec`#

Compares the set fields of spec with pool pool's template: PoolSpecMismatch (with a readable diff) when they differ.

async def check_pool_spec(self, pool: str, spec: SandboxSpec) -> None

Parameter	Type	Default
`pool`	`String`	required
`spec`	`SandboxSpec`	required

Async · Raises CuaError (PoolSpecMismatch)

`Fleet.delete_pool`#

Deletes a pool, its namespace and its same-named template.

async def delete_pool(self, name: str) -> None

Parameter	Type	Default
`name`	`String`	required

Async · Raises CuaError

`Fleet.export_pool`#

Reads pool name back as the shared model, with its fleets_pool Terraform block.

async def export_pool(self, name: str) -> FleetPoolExport

Parameter	Type	Default
`name`	`String`	required

Returns FleetPoolExport · Async · Raises CuaError

`Fleet.get_pool`#

Looks up a pool.

async def get_pool(self, name: str) -> FleetPool

Parameter	Type	Default
`name`	`String`	required

Returns FleetPool · Async · Raises CuaError

`Fleet.list_pools`#

Lists pools in a namespace.

async def list_pools(self, namespace: str) -> List[FleetPool]

Parameter	Type	Default
`namespace`	`String`	required

Returns Vec<FleetPool> · Async · Raises CuaError

`Fleet.list_templates`#

Lists templates in a namespace as JSON resources.

async def list_templates(self, namespace: str) -> List[str]

Parameter	Type	Default
`namespace`	`String`	required

Returns Vec<String> · Async · Raises CuaError

`Fleet.pool_image_info`#

The image pool name's template runs, as a claim on it reports it (Sandbox.image_info): pinned by the resolver (cached per pool), or the template reference with empty pinned_ref/digest when the registry cannot be read. None when the template names no image.

async def pool_image_info(self, name: str) -> Optional[ImageInfo]

Parameter	Type	Default
`name`	`String`	required

Returns Option<ImageInfo> · Async · Raises CuaError

`Fleet.set_pool_replicas`#

Sets warm replicas (0 suspends).

async def set_pool_replicas(self, name: str, replicas: int) -> FleetPool

Parameter	Type	Default
`name`	`String`	required
`replicas`	`u32`	required

Returns FleetPool · Async · Raises CuaError

`Fleet.usage_pricing`#

This account's Cua Cloud rates (GET /api/config), reused for five minutes. None when Fleet answers without rates: show no price rather than a guess.

async def usage_pricing(self) -> Optional[FleetUsagePricing]

Returns Option<FleetUsagePricing> · Async · Raises CuaError

`Fleet.wait_pool_ready`#

Waits for at least one ready replica.

async def wait_pool_ready(self, name: str, timeout_ms: int) -> FleetPool

Parameter	Type	Default
`name`	`String`	required
`timeout_ms`	`u32`	required

Returns FleetPool · Async · Raises CuaError

`FleetPools`#

Managed pools: what Sandboxes.create without a pool uses.

Returned by Fleet.pools.

Method	Description
`gc`	Deletes managed pools idle for `idle_seconds` (default 1800) and stuck Pending/Failed managed claims past their TTL.
`gc_pools`	`FleetPools.gc` restricted to the named managed pools: each is deleted (with its namespace) once it has no claims and has been idle for `idle_seconds` (default 0, i.e. now).
`list`	This account's managed pools.

`FleetPools.gc`#

Deletes managed pools idle for idle_seconds (default 1800) and stuck Pending/Failed managed claims past their TTL.

async def gc(self, idle_seconds: Optional[int]) -> FleetGcReport

Parameter	Type	Default
`idle_seconds`	`Option<u32>`	required

Returns FleetGcReport · Async · Raises CuaError

`FleetPools.gc_pools`#

FleetPools.gc restricted to the named managed pools: each is deleted (with its namespace) once it has no claims and has been idle for idle_seconds (default 0, i.e. now). Pools with live claims are kept, so a pool another process is using survives. Tests use this to remove the pools they created.

async def gc_pools(self, names: List[str], idle_seconds: Optional[int]) -> FleetGcReport

Parameter	Type	Default
`names`	`Vec<String>`	required
`idle_seconds`	`Option<u32>`	required

Returns FleetGcReport · Async · Raises CuaError

`FleetPools.list`#

This account's managed pools.

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

Returns Vec<FleetManagedPool> · Async · Raises CuaError

`SandboxSpec` record#

What a sandbox runs: the one model behind Sandbox.create, managed pools and Fleet.apply. Unset fields keep Fleet's defaults (and are not compared by Fleet.check_pool_spec).

Field	Type	Default	Description
`image`	`String`	`""`	Image (a container image runs on gVisor, a containerDisk on KubeVirt).
`command`	`Option<Vec<String>>`	`None`	argv replacing the image ENTRYPOINT.
`args`	`Option<Vec<String>>`	`None`	Arguments replacing the image CMD.
`env`	`HashMap<String, String>`	`[:]`	Plain environment variables (not secrets).
`services`	`HashMap<String, u16>`	`[:]`	Named services (name → guest port).
`readiness`	`Option<ReadinessProbe>`	`None`	Readiness probe (`port`, or a declared `service`; `http_path` for HTTP). A replica binds a claim only once it passes.
`cpu`	`Option<u32>`	`None`	vCPUs.
`memory_mb` / `memoryMb`	`Option<u32>`	`None`	Memory (MiB).
`efi`	`bool`	`false`	UEFI firmware (Windows images).
`sidecars`	`Vec<Container>`	`[]`	Extra containers sharing the sandbox's network namespace.
`registry_secret` / `registrySecret`	`Option<RegistrySecret>`	`None`	Credentials for a private image: stored as the pool's `cua-registry-*` pull Secret.
`registry_secret_name` / `registrySecretName`	`Option<String>`	`None`	An existing `cua-registry-*` pull Secret in the pool namespace (instead of `registry_secret`).
`process_mode` / `processMode`	`Option<String>`	`None`	`Legacy` or `Run` (`vmTemplate.processMode`).
`claim_secrets` / `claimSecrets`	`bool`	`false`	Per-claim secrets: claims may carry a token delivered at `/run/cua/env-token`.

`PoolOptions` record#

How a pool keeps capacity for a SandboxSpec.

Field	Type	Default	Description
`runtime`	`Option<String>`	`None`	`kubevirt` or `gvisor`. Unset: from the image.
`replicas`	`Option<u32>`	`None`	Replicas of a pool without autoscaling (default 1).
`warm`	`Option<bool>`	`None`	Keep one sandbox warm (`minPoolSize: 1`).
`min_pool_size` / `minPoolSize`	`Option<u32>`	`None`	Autoscaling floor.
`max_pool_size` / `maxPoolSize`	`Option<u32>`	`None`	Autoscaling ceiling.
`idle_ttl_seconds` / `idleTtlSeconds`	`Option<u32>`	`None`	Delete the pool after this many seconds without claims.
`ttl_policy` / `ttlPolicy`	`Option<String>`	`None`	`Retain` or `Cascade`: what TTL expiry deletes.
`pool_ttl_seconds` / `poolTtlSeconds`	`Option<u32>`	`None`	Pool creation-age TTL (seconds).
`claim_ttl_seconds` / `claimTtlSeconds`	`Option<u32>`	`None`	Default TTL (seconds) of claims made on the pool through this SDK.

`FleetPoolExport` record#

A pool read back as the shared model, plus its Terraform block.

Returned by Fleet.export_pool.

Field	Type	Description
`spec`	`SandboxSpec`	What the pool's sandboxes run.
`options`	`PoolOptions`	The pool's capacity settings.
`runtime`	`String`	The runtime.
`terraform`	`String`	A `fleets_pool` resource block (attributes the provider lacks yet are commented).

`FleetPool` record#

A pool.

Returned by Fleet.apply, Fleet.apply_pool, Fleet.get_pool, Fleet.list_pools, Fleet.set_pool_replicas, Fleet.wait_pool_ready.

Field	Type	Description
`name`	`String`	Name.
`namespace`	`String`	Namespace.
`replicas`	`u32`	Desired replicas.
`ready_replicas` / `readyReplicas`	`Option<u32>`	Ready replicas, when reported.
`json`	`String`	The resource as JSON.

`FleetPoolSpec` record#

A warm pool spec (Pool.apply semantics: pool, namespace and template share name). Deprecated: use SandboxSpec + PoolOptions with Fleet.apply.

Field	Type	Default	Description
`name`	`String`		Pool name (globally unique on Fleet).
`image`	`String`		containerDisk (kubevirt) or pod image (gvisor).
`runtime`	`Option<String>`	`None`	`kubevirt` (default) or `gvisor`.
`replicas`	`Option<u32>`	`None`	Warm replicas (default 1).
`cpu`	`Option<u32>`	`None`	vCPUs.
`memory_mb` / `memoryMb`	`Option<u32>`	`None`	Memory (MiB).
`services`	`HashMap<String, u16>`	`[:]`	Services (name → port). Default `{"env": 3211}`.
`readiness_tcp_port` / `readinessTcpPort`	`Option<u16>`	`None`	Optional TCP readiness probe port.
`efi`	`bool`	`false`	UEFI firmware (Windows images).
`command`	`Option<Vec<String>>`	`None`	Pod runtimes: entrypoint override.
`ttl_seconds_after_created` / `ttlSecondsAfterCreated`	`Option<u32>`	`None`	Pool TTL after creation (seconds).

`FleetManagedPool` record#

A managed pool (cua-auto-*, or a legacy cua-eph-*).

Returned by FleetPools.list.

Field	Type	Description
`name`	`String`	Pool (= namespace = template) name.
`managed`	`bool`	Created by the SDK (labeled), not only matching the prefix.
`spec_hash` / `specHash`	`Option<String>`	Spec hash label (first 32 hex digits).
`image`	`Option<String>`	Template image.
`replicas`	`u32`	Current replicas (KEDA-owned).
`ready_replicas` / `readyReplicas`	`Option<u32>`	Ready replicas.
`max_pool_size` / `maxPoolSize`	`Option<u32>`	Autoscaling ceiling.
`claims`	`u32`	Claims in the pool.
`bound_claims` / `boundClaims`	`u32`	Bound claims.
`last_used_unix` / `lastUsedUnix`	`Option<i64>`	Last use (unix seconds).
`created_unix` / `createdUnix`	`Option<i64>`	Creation (unix seconds).
`expires_unix` / `expiresUnix`	`Option<i64>`	Backstop expiry (unix seconds).
`terminating`	`bool`	Being deleted.

`FleetGcReport` record#

What a pool GC did.

Returned by FleetPools.gc, FleetPools.gc_pools.

Field	Type	Description
`deleted_pools` / `deletedPools`	`Vec<String>`	Deleted pools.
`deleted_namespaces` / `deletedNamespaces`	`Vec<String>`	Deleted leftover namespaces.
`deleted_claims` / `deletedClaims`	`Vec<String>`	Deleted stuck claims (`namespace/name`).
`kept`	`Vec<String>`	Kept pools.
`errors`	`Vec<String>`	Non-fatal errors.

`fleet_generate_claim_token`#

A fresh per-claim env token (64 hex characters).

def fleet_generate_claim_token() -> str

Returns String

Fleet

Fleet#

Fleet.apply#

Fleet.apply_pool#

Fleet.apply_pool_template#

Fleet.billing_status#

Fleet.check_pool_spec#

Fleet.delete_pool#

Fleet.export_pool#

Fleet.get_pool#

Fleet.list_pools#

Fleet.list_templates#

Fleet.pool_image_info#

Fleet.set_pool_replicas#

Fleet.usage_pricing#

Fleet.wait_pool_ready#

FleetPools#

FleetPools.gc#

FleetPools.gc_pools#

FleetPools.list#

SandboxSpec record#

PoolOptions record#

FleetPoolExport record#

FleetPool record#

FleetPoolSpec record#

FleetManagedPool record#

FleetGcReport record#

fleet_generate_claim_token#

Fleet#

Fleet.apply#

Fleet.apply_pool#

Fleet.apply_pool_template#

Fleet.billing_status#

Fleet.check_pool_spec#

Fleet.delete_pool#

Fleet.export_pool#

Fleet.get_pool#

Fleet.list_pools#

Fleet.list_templates#

Fleet.pool_image_info#

Fleet.set_pool_replicas#

Fleet.usage_pricing#

Fleet.wait_pool_ready#

FleetPools#

FleetPools.gc#

FleetPools.gc_pools#

FleetPools.list#

SandboxSpec record#

PoolOptions record#

FleetPoolExport record#

FleetPool record#

FleetPoolSpec record#

FleetManagedPool record#

FleetGcReport record#

fleet_generate_claim_token#

`Fleet`#

`Fleet.apply`#

`Fleet.apply_pool`#

`Fleet.apply_pool_template`#

`Fleet.billing_status`#

`Fleet.check_pool_spec`#

`Fleet.delete_pool`#

`Fleet.export_pool`#

`Fleet.get_pool`#

`Fleet.list_pools`#

`Fleet.list_templates`#

`Fleet.pool_image_info`#

`Fleet.set_pool_replicas`#

`Fleet.usage_pricing`#

`Fleet.wait_pool_ready`#

`FleetPools`#

`FleetPools.gc`#

`FleetPools.gc_pools`#

`FleetPools.list`#

`SandboxSpec` record#

`PoolOptions` record#

`FleetPoolExport` record#

`FleetPool` record#

`FleetPoolSpec` record#

`FleetManagedPool` record#

`FleetGcReport` record#

`fleet_generate_claim_token`#

`Fleet`#

`Fleet.apply`#

`Fleet.apply_pool`#

`Fleet.apply_pool_template`#

`Fleet.billing_status`#

`Fleet.check_pool_spec`#

`Fleet.delete_pool`#

`Fleet.export_pool`#

`Fleet.get_pool`#

`Fleet.list_pools`#

`Fleet.list_templates`#

`Fleet.pool_image_info`#

`Fleet.set_pool_replicas`#

`Fleet.usage_pricing`#

`Fleet.wait_pool_ready`#

`FleetPools`#

`FleetPools.gc`#

`FleetPools.gc_pools`#

`FleetPools.list`#

`SandboxSpec` record#

`PoolOptions` record#

`FleetPoolExport` record#

`FleetPool` record#

`FleetPoolSpec` record#

`FleetManagedPool` record#

`FleetGcReport` record#

`fleet_generate_claim_token`#