Sandbox

One running machine of a pool, bound to at most one claim.

A sandbox is created by its pool, never directly. status.sandbox of a bound claim names it; the SDK returns it as a FleetSandbox (namespace, claim, name and services).

On this page: Object · SDK

The sandbox object#

apiVersion: osgym.cua.ai/v1alpha1, kind: OSGymSandbox, in the pool's namespace. Plural osgymsandboxes, short name osbx. 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.

Status#

Set by Fleet; read-only.

Field	Type	Default	Description
`status.message`	`string`	none	Human-readable detail, set when the OSGymSandbox is stuck (e.g. spec.vmTemplate.containerDiskImage missing).
`status.phase`	`string`	none	`Pending`, `Ready` or `Terminating`.
`status.ready`	`boolean`	none	Whether the sandbox is ready.
`status.resetIssuedAt`	`string`	none	When Fleet began restarting the sandbox to return it to its pool.
`status.resetVmiUid`	`string`	none	Identifies the VM instance that restart replaces.
`status.runtime`	`string`	none	Runtime that provisioned the sandbox: `macos`, `gvisor`, or empty for `kubevirt`.
`status.service`	`string`	none	In-cluster DNS name of the sandbox's Service.
`status.vmName`	`string`	none	Name of the sandbox's VM (`kubevirt`).

SDK#

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

Method	Returns	Description
`Fleet.attach_claim(namespace, name)`	`FleetSandbox`	Waits for a named claim to bind.
`Fleet.service_url(sandbox, service)`	`string`	The gateway URL of a sandbox service (needs the Fleet bearer).