Sandbox - IDYL Docs

A Sandbox runs a temporary pod template until its TTL expires.

Minimal manifest

kind: Sandbox
metadata:
  name: debug-shell
  subnet: "100000000001"
spec:
  ttl: 2h
  template:
    spec:
      containers:
        - name: main
          imageURI: ubuntu:24.04
          resources:
            requests:
              cpu: 500m
              memory: 512Mi

Example manifest

kind: Sandbox
metadata:
  name: dev
  subnet: "100000000001"
  labels:
    app: dev
spec:
  ttl: 2h
  lifecycle:
    mode: hold_open
  template:
    metadata:
      labels:
        workload: dev
    spec:
      restartPolicy: never
      isolation:
        class: secure-container
      containers:
        - name: main
          imageURI: ubuntu:24.04
          resources:
            requests:
              cpu: 1
              memory: 1Gi
            limits:
              cpu: 2
              memory: 4Gi
              disk: 20Gi

Field reference

kindstringRequired

Resource kind. The value is case-sensitive.

Value Sandbox

metadataobjectRequired

Top-level workload metadata.

metadata.namespaceobjectOptional

Optional namespace scope embedded in the manifest. CLI flags override these values.

Resolved from CLI context or flags

metadata.namespace.accountIdstringOptional

Account that owns the namespace. The CLI can resolve this from context or —account-id.

Format 12-digit account ID

metadata.namespace.namespacestringOptional

Namespace name. The CLI can resolve this from context or —namespace.

metadata.subnetstringConditional

Canonical subnet identifier where the workload should run.

Resolved from CLI context or the —subnet flag

metadata.namestringRequired

Stable workload name within the namespace.

metadata.labelsmap[string]stringOptional

User-defined labels for grouping, filtering, and ownership metadata.

metadata.annotationsmap[string]stringOptional

User-defined annotations for descriptive metadata that is not used for identity.

specobjectRequired

Desired Sandbox configuration.

spec.ttlstringRequired

How long the Sandbox may exist before it expires.

Format Go duration string such as 15m, 2h, or 24h

spec.lifecycleobjectOptional

Controls how the Sandbox process is started and kept available. If omitted, IDYL keeps the Sandbox alive until its TTL expires or the Sandbox is deleted.

Default hold_open

spec.lifecycle.modestringOptional

Selects whether IDYL holds the Sandbox open, runs the image’s default entrypoint and command, or runs a user-supplied command. If omitted, hold_open is used.

Possible enum values:

hold_open
image_entrypoint
command

spec.templateobjectRequired

Pod template owned by the Sandbox.

spec.template.metadataobjectOptional

Metadata copied to pods created from this template.

spec.template.metadata.labelsmap[string]stringOptional

Labels copied to pods created from this template.

spec.template.metadata.annotationsmap[string]stringOptional

Annotations copied to pods created from this template.

spec.template.specobjectRequired

Pod spec used by this template.

spec.template.spec.restartPolicystringOptional

Container restart behavior.

Possible enum values:

always
on_failure
never

spec.template.spec.platformstringOptional

Workload OS and architecture. If omitted, IDYL resolves the platform from policy and available capacity.

Possible enum values:

linux/amd64
linux/arm64

spec.template.spec.isolationobjectOptional

Requested execution isolation boundary. If omitted, IDYL resolves isolation from subnet policy.

Possible enum values:

container
secure-container

spec.template.spec.isolation.classstringRequired

Requested execution isolation boundary.

Possible enum values:

container
secure-container

spec.template.spec.networkobjectOptional

Workload network intent. If omitted, the workload has no explicit network posture unless policy requires network intent.

Possible enum values:

none
restricted-egress
unrestricted

spec.template.spec.network.classstringRequired

Requested workload network policy.

Possible enum values:

none
restricted-egress
unrestricted

spec.template.spec.network.egressobjectOptional

Allowed outbound destinations for restricted-egress workloads.

Format Restricted egress allow rules

spec.template.spec.network.egress.allowarray[string]Optional

Structured allow rules such as “dns” or “tcp:443:api.example.com”. TCP targets must be DNS hostnames, not IP literals.

Possible enum values:

dns
tcp:<port>:<dns-hostname>

spec.template.spec.network.egress.denyLocalNetworksbooleanOptional

Must be true when network.egress.allow is set. Local networks remain denied while the listed destinations are allowed.

Value true

spec.template.spec.gpuquantity stringOptional

Pod-level GPU requirement. GPU is a physical host device requirement, not a per-container resource. All containers in the pod share GPU access.

Examples h100, 2:h100, nvidia:24Gi

spec.template.spec.requiremap[string]stringOptional

Host capability requirements, for example cuda: ”>=13.0”. The pod is scheduled only on nodes that satisfy every requirement.

Format Exact version or >= minimum version

spec.template.spec.placementobjectOptional

Restricts scheduling to a fleet or a single node inside the workload’s subnet. If omitted, the pod may run anywhere in the subnet.

Format Exactly one of fleet or node

spec.template.spec.placement.fleetstringOptional

Restricts scheduling to eligible members of this fleet.

Format 12-digit fleet ID

spec.template.spec.placement.nodestringOptional

Restricts scheduling to exactly this node.

Format Node ID

spec.template.spec.containersarrayRequired

Containers that run in the pod.

Requirement At least one container

spec.template.spec.containers[].namestringRequired

Container name, unique within the pod.

spec.template.spec.containers[].imageURIstringRequired

Container image reference, such as nginx:latest, ubuntu:22.04, or a private registry image.

spec.template.spec.containers[].imageDigeststringOptional

Optional image digest for verification, for example sha256:abc123…. When provided, it is appended to the registry image reference as image@sha256:abc123.

Example sha256:…

spec.template.spec.containers[].imagePullPolicystringOptional

When the runtime should pull the image.

Possible enum values:

always
never
if_not_present

spec.template.spec.containers[].imagePullSecretstringOptional

References a stored RegistryCredential secret used to authenticate image pulls.

Value secret://name or secret://namespace/name

spec.template.spec.containers[].commandarray[string]Optional

Overrides the container image’s ENTRYPOINT. If empty, the image’s default ENTRYPOINT is used. If set without args, the image’s default CMD is still used with the new entrypoint.

spec.template.spec.containers[].argsarray[string]Optional

Overrides the container image’s CMD. If empty, the image’s default CMD is used.

spec.template.spec.containers[].envarrayOptional

Environment variables to set in the container.

spec.template.spec.containers[].env[].namestringRequired

Environment variable name.

Pattern [a-zA-Z_][a-zA-Z0-9_]*

spec.template.spec.containers[].env[].valuestringRequired

Environment variable value.

spec.template.spec.containers[].resourcesobjectConditional

Container resource requests and limits.

Requirement CPU or memory must be set on at least one container

spec.template.spec.containers[].resources.requestsobjectOptional

Resources used for scheduling. If a request is omitted but a limit is set for that resource, the limit is used as the effective request.

spec.template.spec.containers[].resources.requests.cpuquantity stringOptional

CPU quantity for this resource entry.

Examples 500m, 0.5, 1

spec.template.spec.containers[].resources.requests.memoryquantity stringOptional

Memory quantity for this resource entry.

Examples 256Mi, 1Gi

spec.template.spec.containers[].resources.requests.diskquantity stringOptional

Disk quantity for this resource entry.

Examples 1Gi, 10G

spec.template.spec.containers[].resources.limitsobjectOptional

Maximum resources allowed for the container.

spec.template.spec.containers[].resources.limits.cpuquantity stringOptional

CPU quantity for this resource entry.

Examples 500m, 0.5, 1

spec.template.spec.containers[].resources.limits.memoryquantity stringOptional

Memory quantity for this resource entry.

Examples 256Mi, 1Gi

spec.template.spec.containers[].resources.limits.diskquantity stringOptional

Disk quantity for this resource entry.

Examples 1Gi, 10G

spec.template.spec.sharedVolumeSizequantity stringOptional

Size of the shared volume mounted for the pod.

Examples 1Gi, 10Gi

spec.template.spec.terminationGracePeriodSecondsintegerOptional

How long the node waits after sending SIGTERM before issuing SIGKILL when stopping the pod’s containers. If omitted, the 30-second default applies. A value of 0 requests an immediate SIGKILL with no graceful period.

Format Whole seconds, >= 0 (default 30)

Read-only fields

IDYL can return these fields when you inspect a workload. Do not include them in authored manifests.

Field	Description
`metadata.id`	IDYL-assigned resource ID.
`metadata.namespace.id`	IDYL-assigned namespace ID.
`metadata.ownerReferences`	Parent workload relationship, such as a ReplicaSet owned by a Deployment.
`metadata.createdAt`	Creation timestamp.
`metadata.updatedAt`	Last update timestamp.
`metadata.deletedAt`	Deletion timestamp, when present.
`metadata.revision`	Revision information returned by IDYL.
`status`	Current observed state returned by IDYL.

Validation notes

kind values are case-sensitive.
At least one container is required in every pod spec.
At least one container must specify CPU or memory in resources.requests or resources.limits, unless the CLI fills those values from configured defaults before sending the workload.
GPU requirements belong at the pod spec gpu path, not under per-container resources.
Environment variable names must be unique within a container and must match [a-zA-Z_][a-zA-Z0-9_]*.

​Minimal manifest

​Example manifest

​Field reference

​Read-only fields

​Validation notes

Minimal manifest

Example manifest

Field reference

Read-only fields

Validation notes