Pool and claim reference

Python Fleet pool configuration, claim acquisition, cleanup, and resource types in cua-sandbox 0.4.3.

Pool and Template are exported by cua_sandbox 0.4.3. These APIs use Fleet credentials independently of the legacy CUA_API_KEY flow. See configuration and authentication.

Pool.apply#

Reconciles a named Fleet pool and its template from an Image:

async def apply(
    image: Image, *, name: str, replicas: int = 1,
    cpu: int | None = None, memory_mb: int | None = None,
    services: dict[str, int] | None = None,
    autoscaling: WarmPoolAutoscaling | None = None,
    ttl_seconds_after_created: int | None = None,
) -> Pool: ...

The method reconciles the pool, then its template. If template reconciliation fails, it attempts to delete the reconciled pool. A returned Pool holds the template reference so that delete() can remove both resources.

Pool lookup, reconciliation, and deletion#

These methods use the typed Fleet requests for explicit configuration:

async def get(name: str) -> Pool: ...
async def reconcile(request: CreatePoolRequest) -> Pool: ...
async def delete(self) -> None: ...

Pool.get() retrieves an existing pool without reconciling its configuration. Pool.reconcile() requires a CreatePoolRequest instance and creates or reconciles the pool described by it. Both return a wrapper with name: str and resource, the underlying Fleet pool resource.

delete() deletes the pool. It also deletes the owned template when called on the result of Pool.apply(). A wrapper returned by get() or reconcile() does not record template ownership; manage that template separately.

PoolAccessDeniedError reports Fleet pool access denial. Choose a pool name owned by the authenticated account; an inaccessible name is not an invitation to overwrite another account's pool.

Pool.claim#

Returns an awaitable that also supports an async context manager:

def claim(
    self, *, spec: ClaimSpec | None = None, name: str | None = None,
    service: str = "server", time_to_start: float | None = None,
    ttl_seconds_after_created: int | None = None,
): ...

await pool.claim() waits for binding and service readiness, then returns a connected Sandbox. Its caller must call close() to release the claim. async with pool.claim() calls close() on exit, including when it reuses a named claim. If acquisition fails, the SDK attempts to release a claim created by that acquisition; it does not release a preexisting claim on that path.

disconnect() only drops the connection. It does not release the claim. See Sandbox lifecycle and ownership.

Pool.create_claim#

Creates a claim without waiting for binding or connecting a service:

async def create_claim(
    self, *, spec: ClaimSpec | None = None, name: str | None = None,
    ttl_seconds_after_created: int | None = None,
): ...

The returned handle has these members. Its concrete class is private; obtain it through create_claim() rather than importing the class.

The caller owns cleanup after create_claim(), including when a later wait() fails. After connecting, Sandbox.close() releases the claim and disconnects.

Expiry and renewal#

The ttl_seconds_after_created convenience parameters accept integer values from 0 through 4294967295, excluding booleans. None omits the field. The schema describes the field as a creation-age TTL; accepting a value at the client does not establish the server's expiry policy. Pool and claim TTLs are configured separately. When supplying an explicit ClaimSpec, set the TTL in that spec instead of passing the convenience parameter.

Sandbox.keep_alive(minutes=...) updates the claim's absolute shutdown time. It does not reset the resource's creation timestamp. See Expire pools and claims for expiry configuration.

Template and resource types#

Template.reconcile(request: CreateTemplateRequest) is async and returns a wrapper with name and resource. TemplateResource is the underlying Fleet template type, distinct from the Template wrapper.

The following types and their named builders are reexported by cua_sandbox:

ClaimSpec, RuntimeKind, Firmware, and ServiceProtocol are also reexported. A ClaimSpec constructor requires keyword arguments sandbox_template_ref, warmpool, bind_deadline, and lifecycle, even when the latter three are None; ttl_seconds_after_created is optional. Builders provide named setters and build() for the types listed above.

These bindings come from the published cua-fleet 0.1.14 dependency, imported as fleet_sdk. Type availability describes the client schema; it does not establish runtime or image support on a deployment.