Template

What each sandbox of a pool runs: image, runtime, size, services and probes.

On this page: Object · REST · SDK · Terraform

The template object#

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

Spec#

Field	Type	Default	Description
`spec.vmTemplate`	`object`	required	What each sandbox runs.
`spec.vmTemplate.args`	`string[]`	none	Arguments (Kubernetes args semantics: they replace the image CMD and follow vmTemplate.command). Runs on pod runtimes (gvisor/macos). On runtime kubevirt it needs processMode: Run and a command (a VM image has no entrypoint to pass them to); without Run the gateway and the pool-operator refuse it.
`spec.vmTemplate.claimSecrets`	`boolean`	none	Opt in to claim-scoped secret delivery (OSGymSandboxClaim spec.secretRef). The pool-operator gives every sandbox an operator-owned Secret, empty while the sandbox is warm, fills it when a claim binds and wipes it on release, so a warm sandbox receives its claimant's secrets without a restart. Pod runtimes mount it read-only as a directory (never subPath) at /run/cua, root-owned, mode 0600; the image keeps its default root user, and its root token-sync helper hands the token to a non-root driver. KubeVirt shares it over virtiofs as tag cua-claim-secrets (the EnableVirtioFsConfigVolumes feature gate is GA from KubeVirt v1.8; older KubeVirt needs it enabled); the guest image mounts that tag read-only at /run/cua. cua-env-driver images enable their await-token mode only when /run/cua is a mount point, so the key env-token becomes /run/cua/env-token. Claims with a secretRef fail on templates without this flag.
`spec.vmTemplate.command`	`string[]`	none	`gvisor` and `macos` only: entrypoint of the sandbox container, overriding the image's.
`spec.vmTemplate.containerDiskImage`	`string`	required	The image: a containerDisk for `kubevirt`, a container image for `gvisor` and `macos`.
`spec.vmTemplate.cpuCores`	`integer`	`4`	Virtual CPUs per sandbox. At least 1.
`spec.vmTemplate.env`	`map of string`	none	Plain environment variables for the sandbox's command (not for secrets: the values are stored in the template and visible to anyone who can read it). Names must match ^[A-Za-z_][A-Za-z0-9_]*$. $(NAME) references in command/args expand as in Kubernetes. Pod runtimes (gvisor/macos) set them on the sandbox container. On runtime kubevirt they need processMode: Run and go to /etc/cua/env (root, 0600) and the command's environment; values must be single-line there. Without Run the gateway and the pool-operator refuse env on kubevirt.
`spec.vmTemplate.firmware`	`"bios" \| "efi"`	`"bios"`	VM firmware for `kubevirt`: `efi` for UEFI-only images such as Windows, `bios` for the Linux images.
`spec.vmTemplate.imagePullPolicy`	`"Always" \| "IfNotPresent" \| "Never"`	none	`gvisor` and `macos` only: when to pull the image (default `IfNotPresent`).
`spec.vmTemplate.imagePullSecret`	`string`	none	Secret in the pool's namespace with registry credentials for a private image. Omit it for a public image.
`spec.vmTemplate.memory`	`string`	`"4Gi"`	Memory per sandbox, as a Kubernetes quantity such as `8Gi`.
`spec.vmTemplate.nestedVirtualization`	`boolean`	`false`	Expose hardware virtualization (KVM) inside the VM.
`spec.vmTemplate.nodeSelector`	`map of string`	none	`gvisor` and `macos` only: node selector of the sandbox pod. Fleet's default fits the runtime.
`spec.vmTemplate.oidc`	`object`	none	Workload identity: Fleet puts an OIDC access token for your account at `/var/run/cua/oidc/token` in the guest and keeps it fresh, so the workload can federate into AWS (`sts:AssumeRoleWithWebIdentity`) or any other provider that trusts the token.
`spec.vmTemplate.oidc.awsRegion`	`string`	`"us-west-2"`	AWS region for AWS SDK calls in the guest.
`spec.vmTemplate.oidc.awsRoleArn`	`string`	none	When set, the guest's AWS SDK assumes this role with the token (environment and `~/.aws/config` are set up).
`spec.vmTemplate.oidc.credentialsSecret`	`string`	required	Secret in the pool's namespace holding the client credentials (`client_id`, `client_secret`) that mint the token.
`spec.vmTemplate.oidc.refreshIntervalSeconds`	`integer`	`1800`	How often the guest refreshes the token (half its one-hour lifetime by default). At least 60.
`spec.vmTemplate.oidc.tokenUrl`	`string`	required	Token endpoint that mints the workload token.
`spec.vmTemplate.probes`	`object (any JSON)`	none	Kubernetes `readinessProbe` and `livenessProbe` for the VM, so a sandbox counts as ready only when the guest serves.
`spec.vmTemplate.processMode`	`"Legacy" \| "Run"`	none	How command, args and env reach the sandbox. Absent or Legacy: unchanged behavior (pod runtimes run them; KubeVirt ignores command and refuses args and env). Run: every runtime runs them with the same semantics. Pod runtimes set them on the sandbox container; KubeVirt writes /etc/cua/env (0600), /etc/cua/command.sh (0700) and cua-command.service into the sandbox's cloud-init Secret, which the guest re-reads on every boot, so warm VMs get it on return-to-pool too. KubeVirt Run needs a Linux guest with cloud-init and systemd.
`spec.vmTemplate.runtime`	`"kubevirt" \| "macos" \| "gvisor"`	`"kubevirt"`	`kubevirt`: each sandbox is a VM booted from `containerDiskImage`. `gvisor`: a gVisor container of the image. `macos`: a macOS sandbox. For `gvisor` and `macos`, `firmware`, `cpuCores` and `memory` are advisory.
`spec.vmTemplate.runtimeClassName`	`string`	none	`gvisor` and `macos` only: RuntimeClass of the sandbox pod. Fleet's default fits the runtime.
`spec.vmTemplate.services`	`object[]`	none	Ports each sandbox publishes, as a Service named `<sandbox>-<name>`. Reach them through service URLs.
`spec.vmTemplate.services[].name`	`string`	required	Service name suffix (sandbox name is prepended).
`spec.vmTemplate.services[].protocol`	`"TCP" \| "UDP"`	`"TCP"`	`TCP` or `UDP`.
`spec.vmTemplate.services[].targetPort`	`integer`	required	Port in the sandbox. 1 to 65535.
`spec.vmTemplate.tolerations`	`object (any JSON)[]`	none	`gvisor` and `macos` only: tolerations of the sandbox pod. Fleet's default fits the runtime.

Fields the SDK adds#

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

Field	Type	Description
`spec.vmTemplate.claimSecrets`	`boolean`	Opts the template into per-claim Secrets: the Secret a claim names in `spec.secretRef` is delivered into the bound sandbox at `/run/cua/env-token`.
`spec.vmTemplate.env`	`map of string`	Environment of the sandbox process.
`spec.vmTemplate.args`	`string[]`	Arguments of the sandbox process.
`spec.vmTemplate.sidecars`	`object[]`	Containers that run next to the sandbox, on every runtime (at most 8). They reach the sandbox at host `main`.
`spec.vmTemplate.processMode`	`"Legacy" \| "Run"`	`Legacy`: pod runtimes run `command`, `args` and `env`; KubeVirt ignores `command` and refuses `args` and `env`. `Run`: every runtime runs them (KubeVirt through cloud-init).

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": "OSGymSandboxTemplate",
  "metadata": {
    "name": "my-pool",
    "namespace": "my-pool"
  },
  "spec": {
    "vmTemplate": {
      "containerDiskImage": "ghcr.io/trycua/linux:24.04-disk",
      "runtime": "kubevirt",
      "services": [
        {
          "name": "env",
          "protocol": "TCP",
          "targetPort": 3211
        }
      ]
    }
  }
}

REST#

Create template#

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

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

Body: the template object (application/json).

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

Errors: 401, 403, 502 (Errors).

List templates#

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

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

Errors: 401, 403, 502 (Errors).

Get template#

GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates/{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 template object.

Errors: 401, 403, 502 (Errors).

Update template#

PATCH /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates/{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 template object (application/merge-patch+json).

Returns: 200 with the template object.

Errors: 401, 403, 502 (Errors).

Delete template#

DELETE /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates/{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.

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_template(pool, spec)`	none	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).
`Fleet.check_pool_spec(pool, spec)`	none	Compares the set fields of `spec` with pool `pool`'s template: `PoolSpecMismatch` (with a readable diff) when they differ.
`Fleet.list_templates(namespace)`	`string[]`	Lists templates in a namespace as JSON resources.

Terraform#

Terraform manages the template as part of its pool: fleets_pool writes a template named <pool>-template from these arguments.

Terraform argument	Template field
`cpu_cores`	`spec.vmTemplate.cpuCores`
`memory`	`spec.vmTemplate.memory`
`container_disk_image`	`spec.vmTemplate.containerDiskImage`
`image_pull_secret`	`spec.vmTemplate.imagePullSecret`
`runtime`	`spec.vmTemplate.runtime`
`firmware`	`spec.vmTemplate.firmware`
`readiness_probe_json`	`spec.vmTemplate.probes`
`liveness_probe_json`	`spec.vmTemplate.probes`
`command`	`spec.vmTemplate.command`
`claim_secrets`	`spec.vmTemplate.claimSecrets`
`service {}`	`spec.vmTemplate.services`