Pool

Warm capacity: how many sandboxes of one template Fleet keeps ready to claim.

On this page: Object · REST · SDK · Terraform

The pool object#

apiVersion: osgym.cua.ai/v1alpha1, kind: OSGymSandboxWarmPool, in the pool's namespace. Plural osgymsandboxwarmpools, short name oswp. metadata is standard Kubernetes object metadata (name, namespace, labels).

Spec#

Field	Type	Default	Description
`spec.autoscaling`	`object`	none	Claim-driven autoscaling. When set, Fleet sizes the pool from its live claims (Pending and Bound) and owns `spec.replicas`: a Pending claim grows the pool, deleting claims shrinks it. Absent: `spec.replicas` is a static size.
`spec.autoscaling.initialPoolSize`	`integer`	`0`	Warm head start: `spec.replicas` starts here when the pool is created, so the first claims bind without a cold start. It then follows claim demand, never below `minPoolSize`. At least 0.
`spec.autoscaling.maxPoolSize`	`integer`	`50`	Most sandboxes the pool scales to. At least 1.
`spec.autoscaling.minPoolSize`	`integer`	`0`	Fewest warm sandboxes kept while autoscaling. `0` lets the pool scale to zero when there are no claims. At least 0.
`spec.idleTtlSeconds`	`integer`	none	Idle TTL in seconds. The pool-operator deletes the pool once it has had no Pending or Bound claims for this long, measured from status.lastActivityTime (or creation when no claim was ever made), when OSGYM_POOL_LIFECYCLE_MODE is enforce. When absent, the pool is never reaped for being idle. At least 0.
`spec.replicas`	`integer`	required	Warm sandboxes to keep ready. With `autoscaling`, Fleet sets it. At least 0.
`spec.sandboxTemplateRef`	`object`	required	The template the pool's sandboxes run.
`spec.sandboxTemplateRef.name`	`string`	required	Name of the OSGymSandboxTemplate to use.
`spec.ttlPolicy`	`"Retain" \| "Cascade"`	none	What expiry of ttlSecondsAfterCreated or idleTtlSeconds deletes. Retain (the behaviour when absent) deletes only the pool. Cascade also deletes the pool's dead unbound claims (TTL passed and older than max(900s, bindDeadline)); it never deletes Bound claims, the namespace or volumes.
`spec.ttlSecondsAfterCreated`	`integer`	none	Creation-age TTL in seconds. When absent, the resource is not automatically reaped based on age. At least 0.

Status#

Set by Fleet; read-only.

Field	Type	Default	Description
`status.lastActivityTime`	`string`	none	When a claim against this pool was last created, bound or released. The idle TTL (spec.idleTtlSeconds) counts from here.
`status.lastClaimedAt`	`string`	none	When a claim last bound a Sandbox from this pool.
`status.readyReplicas`	`integer`	none	Sandboxes ready to be claimed.
`status.replicas`	`integer`	none	Sandboxes the pool currently owns.
`status.selector`	`string`	none	Label selector for the pool's OSGymSandboxes.

Example#

What the SDK sends for a default pool of the cua Linux image (PoolSpec::new, built by cua-fleet).

{
  "apiVersion": "osgym.cua.ai/v1alpha1",
  "kind": "OSGymSandboxWarmPool",
  "metadata": {
    "name": "my-pool",
    "namespace": "my-pool"
  },
  "spec": {
    "replicas": 1,
    "sandboxTemplateRef": {
      "name": "my-pool"
    }
  }
}

REST#

Create pool#

POST /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.

Body: the pool object (application/json).

Returns: 200, 201, 202 with the pool object.

The SDK first creates the namespace named after the pool (Create a namespace) and deletes it again if the pool is refused.

Errors: 401, 403, 502 (Errors).

List pools#

GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.

Returns: 200 with {"items": [...]}, a list of the pool object.

Errors: 401, 403, 502 (Errors).

Get pool#

GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{name}/osgymsandboxwarmpools/{name}

A pool's namespace is its name, so the name fills both slots.

Parameter	In	Description
`name`	path	The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters).

Returns: 200 with the pool object.

Errors: 401, 403, 502 (Errors).

Update pool#

PATCH /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools/{name}

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.
`name`	path	The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters).

Body: a JSON merge patch of the pool object (application/merge-patch+json).

Returns: 200 with the pool object.

Errors: 401, 403, 502 (Errors).

Delete pool#

DELETE /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools/{name}

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.
`name`	path	The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters).

Returns: 200, 202, 204 with no body.

404 is treated as success: the object is already gone.

The SDK then deletes the namespace, with everything left in it.

Errors: 401, 403, 502 (Errors).

SDK#

Methods of the Fleet handle (cua.fleet()), with signatures in every language in the Cua SDK reference.

Method	Returns	Description
`Fleet.apply_pool(spec)`	`FleetPool`	Deprecated: use `Fleet::apply`.
`Fleet.apply(name, spec, options)`	`FleetPool`	Reconciles pool `name` (= namespace = template) to run `spec` with `options`: the one pool writer (rolls a new pool back if the template fails).
`Fleet.get_pool(name)`	`FleetPool`	Looks up a pool.
`Fleet.list_pools(namespace)`	`FleetPool[]`	Lists pools in a namespace.
`Fleet.set_pool_replicas(name, replicas)`	`FleetPool`	Sets warm replicas (0 suspends).
`Fleet.wait_pool_ready(name, timeout_ms)`	`FleetPool`	Waits for at least one ready replica.
`Fleet.export_pool(name)`	`FleetPoolExport`	Reads pool `name` back as the shared model, with its `fleets_pool` Terraform block.
`Fleet.delete_pool(name)`	none	Deletes a pool, its namespace and its same-named template.
`Fleet.ephemeral_pool_name()`	`string`	A random ephemeral pool name (`cua-eph-<hex>`).
`Fleet.pools()`	`FleetPools`	Managed pools (list, gc).
`FleetPools.list()`	`FleetManagedPool[]`	This account's managed pools.
`FleetPools.gc(idle_seconds)`	`FleetGcReport`	Deletes managed pools idle for `idle_seconds` (default 1800) and stuck Pending/Failed managed claims past their TTL.
`FleetPools.gc_pools(names, idle_seconds)`	`FleetGcReport`	`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).

Terraform#

Resource fleets_pool of the trycua/fleets provider. A Cua Fleet computer-use pool: an OSGymSandboxWarmPool and its OSGymSandboxTemplate. The pool name also owns its same-named namespace.

main.tf

terraform {
  required_providers {
    fleets = {
      source  = "trycua/fleets"
      version = "0.2.0"
    }
  }
}
 
provider "fleets" {
  endpoint = "https://run.cua.ai"
}
 
resource "fleets_pool" "linux" {
  name                 = "linux-pool"
  cpu_cores            = 4
  memory               = "8Gi"
  container_disk_image = "ghcr.io/trycua/linux:24.04-disk"
  runtime              = "kubevirt"
  firmware             = "bios"
 
  service {
    name        = "env"
    target_port = 3211
    protocol    = "TCP"
  }
 
  autoscaling {
    min_pool_size     = 0
    initial_pool_size = 1
    max_pool_size     = 5
  }
}
 
output "linux_pool" {
  value = {
    name             = fleets_pool.linux.name
    namespace        = fleets_pool.linux.namespace
    target_replicas  = fleets_pool.linux.replicas
    current_replicas = fleets_pool.linux.current_replicas
    ready_replicas   = fleets_pool.linux.ready_replicas
  }
}

Arguments#

Exactly one of replicas or autoscaling is required.

Argument	Type	Default	Description
`name`	`string`	required	Pool and namespace DNS label. Changing it replaces the resource. 1 to 63 characters. Matches `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`.
`replicas`	`number`	none	Static desired warm pool size. Exactly one of `replicas` or `autoscaling` must be configured. In autoscaling mode, do not configure it; after apply and refresh it reports the current pool target. At least 0.
`cpu_cores`	`number`	required	Virtual CPUs per sandbox. At least 1.
`memory`	`string`	required	Kubernetes memory quantity per sandbox.
`container_disk_image`	`string`	required	OCI containerDisk or runtime image.
`image_pull_secret`	`string`	none	Optional image pull secret. Omit it for an anonymous public-image pull.
`runtime`	`string`	`"kubevirt"`	`kubevirt`, `macos`, or `gvisor`; defaults to `kubevirt`.
`firmware`	`string`	`"bios"`	`bios` or `efi`; defaults to `bios`.
`readiness_probe_json`	`string (JSON)`	none	Kubernetes probe objects encoded as JSON.
`liveness_probe_json`	`string (JSON)`	none	Kubernetes probe objects encoded as JSON.
`command`	`list(string)`	none	Entrypoint command list (replaces the image entrypoint). Pod runtimes (`gvisor`, `macos`) run it; KubeVirt ignores it.
`claim_secrets`	`bool`	none	Opt in to claim-scoped secret delivery at `/run/cua` (the per-claim env token and a claim's `secretRef`). Claims with a `secretRef` fail on pools without it.
`ttl_seconds_after_created`	`number`	none	Delete the pool this many seconds after it was created. Omit it to never reap by age. 0 to 4294967295.
`idle_ttl_seconds`	`number`	none	Delete the pool after this many seconds with no Pending or Bound claims. Omit it to never reap for idleness. 0 to 4294967295.
`ttl_policy`	`string`	none	What a TTL expiry deletes: `Retain` (the pool only, the behavior when omitted) or `Cascade` (also the pool's dead unbound claims; never Bound claims, the namespace or volumes).

`service` block#

Repeatable block. Repeatable service with name, target_port, and optional protocol.

Argument	Type	Default	Description
`service.name`	`string`	required	Service name suffix (sandbox name is prepended).
`service.target_port`	`number`	required	Port on the VM pod to forward to. 1 to 65535.
`service.protocol`	`string`	`"TCP"`	`TCP` or `UDP`.

`autoscaling` block#

Block. Claim-driven autoscaling limits. Exactly one of replicas or autoscaling is required.

Argument	Type	Default	Description
`autoscaling.min_pool_size`	`number`	`0`	Minimum warm pool size while autoscaling is enabled. At least 0.
`autoscaling.initial_pool_size`	`number`	`0`	Initial pool target when autoscaling starts. At least 0.
`autoscaling.max_pool_size`	`number`	`50`	Maximum autoscaled pool size; defaults to `50` when omitted. At least 1.

Attributes#

Read-only, set by the provider.

Attribute	Type	Description
`id`	`string`	The pool name.
`namespace`	`string`	The pool's namespace (the pool name).
`template_name`	`string`	Name of the OSGymSandboxTemplate backing this pool.
`current_replicas`	`number`	Sandboxes the warm pool currently owns.
`ready_replicas`	`number`	Sandboxes that are ready to be claimed.

replicas is also set in autoscaling mode: it reports the current pool target.

Import#

Import IDs are pool names.

terraform import fleets_pool.linux training-linux

Pool

The pool object#

Spec#

Status#

Example#

REST#

Create pool#

List pools#

Get pool#

Update pool#

Delete pool#

SDK#

Terraform#

Arguments#

service block#

autoscaling block#

Attributes#

Import#

The pool object#

Spec#

Status#

Example#

REST#

Create pool#

List pools#

Get pool#

Update pool#

Delete pool#

SDK#

Terraform#

Arguments#

service block#

autoscaling block#

Attributes#

Import#

`service` block#

`autoscaling` block#

`service` block#

`autoscaling` block#