Claim

A lease on one sandbox from a pool, until it is released or expires.

On this page: Object · REST · SDK

The claim object#

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

Spec#

Field	Type	Default	Description
`spec.bindDeadline`	`integer`	none	Seconds the claim may stay Pending before it is marked Failed (Fleet's default and the SDK's value: 900). A Pending claim is what grows an autoscaled pool, so leave room for a cold boot. At least 0.
`spec.lifecycle`	`object`	none	When the claim expires and what happens to its sandbox.
`spec.lifecycle.autoRenew`	`boolean`	`false`	Set by Fleet on claims it renews itself. Leave it `false`.
`spec.lifecycle.shutdownPolicy`	`string`	`"Retain"`	`Retain`: when the claim is deleted, the sandbox returns to the pool and restarts clean. `Delete`: the sandbox is destroyed and the pool creates a new one.
`spec.lifecycle.shutdownTime`	`string`	none	Absolute UTC expiry (RFC 3339). Fleet deletes the claim, and releases its sandbox, once it passes. Renew by patching it forward.
`spec.sandboxTemplateRef`	`object`	required	The template of the pool to claim from.
`spec.sandboxTemplateRef.name`	`string`	required	OSGymSandboxTemplate the warm pool's OSGymSandboxes use.
`spec.secretRef`	`object`	none	Secret in the claim's namespace whose keys the pool-operator delivers as files into the bound sandbox once it binds, without restarting it: each key becomes /run/cua/<key> (mode 0600), e.g. env-token -> /run/cua/env-token for cua-env-driver. The data is copied into an operator-owned per-sandbox Secret, never into the claim status, and is wiped when the claim is released. The name must be cua-claim-<claim name>, and the claim's template must set vmTemplate.claimSecrets, or the claim fails.
`spec.secretRef.name`	`string`	required	Secret name (must start with cua-claim-). At most 253 characters. Matches `^cua-claim-[a-z0-9]([-a-z0-9]*[a-z0-9])?$`.
`spec.ttlSecondsAfterCreated`	`integer`	none	Creation-age TTL in seconds. When absent, the resource is not automatically reaped based on age. At least 0.
`spec.warmpool`	`string`	`"default"`	Where to take a sandbox from: `default` (the pool running the template), `none`, or a pool name.

Status#

Set by Fleet; read-only.

Field	Type	Default	Description
`status.conditions`	`object[]`	none	Kubernetes conditions of the claim.
`status.conditions[].lastTransitionTime`	`string`	none	When the condition last changed (RFC 3339).
`status.conditions[].message`	`string`	none	Human-readable detail.
`status.conditions[].reason`	`string`	none	Machine-readable reason.
`status.conditions[].status`	`string`	none	`True`, `False` or `Unknown`.
`status.conditions[].type`	`string`	none	Condition type.
`status.phase`	`string`	none	`Pending`, `Bound` or `Failed`.
`status.sandbox`	`object`	none	The bound sandbox.
`status.sandbox.name`	`string`	none	Name of the bound sandbox.
`status.sandbox.service`	`string`	none	In-cluster DNS name of the sandbox's Service.

Fields the SDK adds#

Written as JSON beyond the published schema; Fleet reads them.

Field	Type	Description
`spec.secretRef.name`	`string`	The claim's `cua-claim-<claim>` Secret. The template must set `claimSecrets`.

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": "OSGymSandboxClaim",
  "metadata": {
    "name": "claim-1",
    "namespace": "my-pool"
  },
  "spec": {
    "bindDeadline": 900,
    "sandboxTemplateRef": {
      "name": "my-pool"
    }
  }
}

REST#

Create claim#

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

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

Body: the claim object (application/json).

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

Errors: 401, 403, 502 (Errors).

List claims#

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

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 claim object.

Errors: 401, 403, 502 (Errors).

Get claim#

GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxclaims/{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 with the claim object.

Errors: 401, 403, 502 (Errors).

Renew claim#

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

Push the claim's spec.lifecycle.shutdownTime forward. That absolute expiry is the only liveness input the pool operator's claim reaper honors, so a holder that outlives its current lease must renew before the deadline passes or the bound sandbox is deleted underneath it. Deliberately narrower than a claim update: nothing else on the claim can be mutated through the SDK.

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 claim object (application/merge-patch+json).

Returns: 200 with the claim object.

Errors: 401, 403, 502 (Errors).

Delete claim#

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

Delete the claim and, when it references a claim-scoped Secret (secret_files), that Secret too. The pool-operator also owner-refs the Secret to the claim, so garbage collection is the backstop.

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.

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.acquire(pool, name, ttl_seconds)`	`FleetSandbox`	Claims a sandbox from a pool and waits for it to bind.
`Fleet.acquire_with(pool, options)`	`FleetSandbox`	`Fleet::acquire` with claim options, including a per-claim env token (bounded wait for its delivery; `ClaimSecretsNotDelivered` releases the claim).
`Fleet.claim(pool, name, ttl_seconds)`	`FleetClaim`	Creates a claim without waiting.
`Fleet.attach_claim(namespace, name)`	`FleetSandbox`	Waits for a named claim to bind.
`Fleet.list_claims(namespace)`	`FleetClaim[]`	Lists claims in a namespace.
`Fleet.keep_alive(namespace, name, seconds)`	`string`	Extends a claim's lease; returns the RFC 3339 shutdown time.
`Fleet.release(namespace, name)`	none	Releases a claim (missing claims are fine).