Policy reference

This page documents every field in a sandbox policy. A policy is carried on a managed runner as the policy field and governs the sandboxes placed on that runner.

Top-level fields

Field	Type	Description
`display_name`	`string`	Human-readable name for the posture this policy describes.
`base`	object	Runtime defaults and attachments applied before the sandbox spec. See `base`.
`constraints`	`PolicyConstraints`	Typed clamps validated against the resolved spec. See `constraints`.
`control_plane_access`	`ControlPlaneAccessPolicy`	Request-time source IP controls for Sandbox API operations. See `control_plane_access`.

An empty policy is valid and supplies no base defaults or explicit constraints. Platform safety gates still apply, and an absent runtime-class allowlist permits no concrete runtime_class pin. The base, constraints, and control_plane_access groups are optional. An absent source IP allowlist adds no source-address restriction.

Resolution order

A sandbox resolves in two stages:

Base: Runtime defaults, then base, then the sandbox spec. The sandbox takes precedence for scalar defaults. List attachments from base are always applied, and administrator-pinned Pod metadata takes precedence when annotation keys overlap.
Constraints: Clamps are validated against the fully resolved spec. A violation is rejected, never silently rewritten.

Because constraints validate the resolved spec rather than the submitted one, a value that base supplied is checked on the same terms as a value the sandbox supplied.

`base`

A fragment of runtime defaults and attachments. On a Kubernetes runner, this is a Pod specification fragment. base is where infrastructure settings live that a sandbox has no business declaring: the scheduler, Node selectors, tolerations, PriorityClass, topology spread, image pull Secrets, platform volumes, DNS configuration, and Pod metadata such as pinned annotations. Security-sensitive fields are rejected outright, including the following:

affinity
Pod and container securityContext.
runtimeClassName
initContainers
Host namespaces.
hostPath volumes.
Non-default ServiceAccounts.

`control_plane_access`

ControlPlaneAccessPolicy restricts Sandbox API requests that select a runner or target a sandbox placed on it. These controls supplement authentication and authorization. They don’t restrict traffic sent directly to services exposed by a sandbox.

Field	Type	Description
`source_ip_allowlist`	`SourceIpAllowlist`	Optional source-address allowlist. Absent means unrestricted by source address. Present but empty denies every public source.

`SourceIpAllowlist`

Field	Type	Description
`cidrs`	`string` list	IPv4 and IPv6 classless inter-domain routing (CIDR) prefixes matched against the client address observed at the API edge. The API accepts at most 256 entries and 16 KiB of CIDR text before normalization.

The API canonicalizes prefixes, removes duplicates, and removes prefixes covered by a broader entry. Invalid CIDRs, including zone-qualified IPv6 addresses, are rejected. 0.0.0.0/0 explicitly permits every IPv4 source. ::/0 explicitly permits every IPv6 source. Access controls are evaluated at request time, separately from create-time specification resolution. Changes apply to new operations on existing sandboxes after policy-cache propagation. Policy administration remains available to administrators regardless of the allowlist. For configuration, stream behavior, errors, and recovery, see Restrict Sandbox API access by source IP.

`constraints`

PolicyConstraints groups the typed clamps a policy enforces. Every group is optional. Omitting a group adds no explicit constraints of that kind, but platform safety gates and the runtime-class restrictions in SecurityConstraints still apply.

Group	Type	Governs
`resources`	`ResourceConstraints`	CPU, memory, and GPU bounds and defaults.
`image`	`ImageConstraints`	Which images a sandbox may run.
`network`	`NetworkConstraints`	Egress and ingress allowlists and defaults.
`security`	`SecurityConstraints`	Privilege, capabilities, and isolation.
`instance`	`InstanceConstraints`	Which Node instance types a sandbox may land on.
`lifecycle`	`LifecycleConstraints`	How long a sandbox may live.
`metadata`	`MetadataConstraints`	Annotation keys and count.
`volumes`	`VolumeConstraints`	Storage media and per-volume size.

`ResourceConstraints`

Field	Type	Description
`max_cpu`	`string`	Maximum CPU a container may request, as a Kubernetes quantity.
`max_memory`	`string`	Maximum memory a container may request.
`min_cpu`	`string`	Minimum CPU a container may request.
`min_memory`	`string`	Minimum memory a container may request.
`default_cpu`	`string`	Default CPU per container. When a container declares neither requests nor limits, a positive default also supplies its CPU limit.
`default_memory`	`string`	Default memory per container. When a container declares neither requests nor limits, a positive default also supplies its memory limit.
`max_gpu_count`	`int64`	Maximum GPUs per container. Omitted means no cap. Explicit `0` forbids GPU requests.
`cpu_ceiling`	`string`	Cap on the sum of resolved CPU requests across all user containers.
`memory_ceiling`	`string`	Cap on resolved memory requests across all user containers plus resolved memory-backed volume sizes.
`require_limits`	`bool`	When `true`, requires every container to have limits after defaults are applied.

max_cpu and max_memory bound each user container’s request. A sandbox with multiple user containers can satisfy each per-container maximum and still exceed cpu_ceiling or memory_ceiling. The memory ceiling also includes the resolved sizes of memory-backed volumes. Ceilings are policy checks on one sandbox. Placement also accounts for runtime overhead, other workloads, and available capacity. Node allocation budgets bound aggregate sandbox requests on each Node. For sizing guidance, see Size sandbox CPU and memory.

`ImageConstraints`

Field	Type	Description
`allowed_registries`	`string` list	Registries a sandbox image may come from. Empty permits any.
`allowed_images`	`string` list	Exact images a sandbox may run. Empty permits any.

`NetworkConstraints`

Network constraints define allowlists for the access a sandbox can request. When a sandbox declares egress, the policy accepts or rejects that declaration without widening it. When the sandbox declares no egress, the policy applies default_egress, unless the sandbox sets deny_egress. Platform DNS and storage access are granted separately. The same constraints bound dynamic network updates.

Field	Type	Description
`allowed_egress`	`EgressRule` list	Egress allowlist, checked when a sandbox is created and during live network updates. When non-empty, every declared rule must fit inside it. Empty permits anything declarable.
`default_egress`	`EgressRule` list	Applied when the sandbox declares no egress, unless it sets `deny_egress`. Displaced entirely by any declaration. Must fit `allowed_egress` and must not contain `https_hostname` rules.
`allowed_ingress`	`IngressRule` list	Ingress allowlist for `CUSTOM`-visibility ports, checked when a sandbox is created and during live network updates. When non-empty, every declared rule must fit inside it. Empty permits anything declarable.
`default_ingress`	`IngressRule` list	Applied when a sandbox exposes a `CUSTOM`-visibility port and declares no ingress, unless it sets `deny_ingress`. Displaced entirely by explicit ingress rules. Must fit `allowed_ingress`.
`deny_https_hostname_rules`	`bool`	When `true`, rejects `https_hostname` rules in `allowed_egress` and sandbox requests. Doesn’t block DNS queries or HTTPS permitted by CIDR rules.
`dns_egress`	`DNSEgressMode`	Controls outbound DNS traffic on UDP/TCP port `53`. Unspecified defaults to `DNS_EGRESS_MODE_ALLOW`. A sandbox can choose `DNS_EGRESS_MODE_DENY`, but can’t request `ALLOW` when the policy requires `DENY`.

When an allowlist is non-empty, containment is checked by destination or source type and port. A declared CIDR must fit the combined allowed CIDR ranges or an any rule. A declared tenant scope requires a matching tenant rule or an any rule, while declaring any requires an any rule.

`EgressRule`

Each rule names exactly one destination, optionally narrowed by port.

Field	Type	Description
`cidr`	`CidrBlock`	An address range, with optional carve-outs.
`https_hostname`	`string`	An HTTPS hostname, exact or with a single leftmost wildcard label, such as `.example.com`. Requires a runner that supports hostname-based HTTPS rules. In `allowed_egress`, `` permits any hostname declaration.
`https_hostname_except`	`string` list	Hostnames excluded from this rule. Valid only with `https_hostname` in `allowed_egress`. Uses the same hostname patterns, except `*`.
`tenant`	`TenantScope`	Other sandboxes, selected by relationship.
`any`	`bool`	All reachable destinations except platform-internal ranges. Use tenant or selector rules to reach other sandboxes or cluster workloads.
`selector`	`SelectorBlock`	Workloads selected by label.
`ports`	`PortRange` list	Ports the rule applies to. Omit for all ports, except for `https_hostname` rules, which permit only TCP `443`.

Hostname rules authorize HTTPS access, not DNS queries. When allowed_egress is non-empty, a declared hostname must fit an allowed hostname pattern, after its exclusions, or an any rule. A CIDR-only allowlist doesn’t permit hostname declarations. Put reusable hostname grants in a sandbox template, not in default_egress. dns_egress controls outbound UDP/TCP port 53 independently. DNS_EGRESS_MODE_ALLOW permits access to the platform resolver. Other resolvers require an egress rule. DNS_EGRESS_MODE_DENY blocks outbound port 53 even when another rule permits it. It doesn’t block locally answered lookups or DNS over other permitted transports, such as HTTPS.

`IngressRule`

Field	Type	Description
`cidr`	`CidrBlock`	An address range, with optional carve-outs.
`tenant`	`TenantScope`	Other sandboxes, selected by relationship.
`any`	`bool`	Any source.
`ports`	`PortRange` list	Ports the rule applies to. Omit for all `CUSTOM`-visibility ports.

Ingress rules apply to existing CUSTOM-visibility ports. They don’t change service visibility and can’t select sources by hostname or label.

`CidrBlock`

Field	Type	Description
`cidr`	`string`	Required. The address range, such as `10.0.0.0/8`.
`except`	`string` list	Ranges carved out of `cidr`. A carve-out narrows only its own rule.

`PortRange`

Field	Type	Description
`protocol`	`string`	Optional. Defaults to TCP.
`port`	`int32`	Required. The port, or the start of a range.
`end_port`	`int32`	Optional. The end of a range.

`TenantScope`

Value	Selects
`TENANT_SCOPE_SAME_USER`	Sandboxes owned by the same user.
`TENANT_SCOPE_SAME_ORG`	Sandboxes in the same organization.
`TENANT_SCOPE_SANDBOX_NETWORK`	Sandboxes on the same sandbox network. Not supported yet. An egress rule using it is rejected.

`SelectorBlock`

Field	Type	Description
`pod_labels`	`string` map	Required. Labels matched on the destination Pod.
`namespace_labels`	`string` map	Optional. Labels matched on the destination Namespace.

Matching uses exact label pairs, but declarations may add labels. When the egress allowlist is non-empty, a declared selector must carry every label pair in a matching selector rule. Both selectors must omit Namespace labels, or both must include them, with the declaration carrying every required Namespace label pair. An any rule never covers selectors, but an empty allowlist permits selector declarations.

`SecurityConstraints`

Field	Type	Description
`allow_privileged`	`bool`	Whether a container may run privileged within the sandbox’s isolation boundary.
`allowed_capabilities`	`string` list	Linux capabilities a container may add.
`allowed_seccomp_profiles`	`string` list	Permitted seccomp profiles, such as `RuntimeDefault` or `Unconfined`.
`allowed_runtime_classes`	`string` list	Runtime classes a sandbox may pin. Fails closed: empty permits no pin at all.
`default_cpu_runtime_class`	`string`	Runtime class applied to a CPU sandbox that pins none.
`default_gpu_runtime_class`	`string`	Runtime class applied to a GPU sandbox that pins none.
`runtime_class_mappings`	`RuntimeClassMapping` list	Maps portable runtime classes to execution targets. See `RuntimeClassMapping`.

Host namespaces aren’t configurable through v1 policy security fields. The former allow_host_network and allow_host_pid fields have been removed. For legacy v1beta2 profiles, see Example: allow a privileged profile posture. allowed_runtime_classes fails closed: an empty or absent list permits no concrete runtime_class pin. Portable class selection through runtime_class_selection uses runtime_class_mappings instead. The policy bounds the in-guest privileges a sandbox may request and the runtime classes it may select.

`RuntimeClassMapping`

A non-empty runtime_class_mappings list enables portable runtime class selection. Each mapped class is available for caller selection. RUNTIME_CLASS_CPU_DEFAULT and RUNTIME_CLASS_GPU_DEFAULT also supply automatic selection for their resource family. Omitting either default class turns off automatic selection for that family. Unmapped classes are unavailable, and concrete runtime_class pins are rejected. Mappings can’t be combined with allowed_runtime_classes, default_cpu_runtime_class, or default_gpu_runtime_class. Each portable class can appear at most once.

Field	Type	Description
`runtime_class`	`RuntimeClass`	Required portable class. Use one of the following values.
`kubernetes_runtime_class_name`	`string`	Non-empty Kubernetes RuntimeClass name. Set exactly one of this field or `node_default`.
`node_default`	`bool`	Set to `true` to use the Node’s default container runtime. Permitted only for `RUNTIME_CLASS_CPU_DEFAULT` or `RUNTIME_CLASS_GPU_DEFAULT`, and only for CoreWeave Kubernetes Service (CKS) placement outside the shared serverless pool.

`RuntimeClass` value	Execution requirement
`RUNTIME_CLASS_CPU_DEFAULT`	Default execution without GPU resources.
`RUNTIME_CLASS_CPU_NESTED_VIRT`	CPU execution with nested virtualization.
`RUNTIME_CLASS_CPU_SNAPSHOT_RESTORE`	CPU execution with virtual machine (VM) state snapshot and restore. File-system snapshots are a separate capability.
`RUNTIME_CLASS_GPU_DEFAULT`	Default execution with GPU resources.

`InstanceConstraints`

Field	Type	Description
`allowed_instance_types`	`string` list	Node instance types a sandbox may land on. Empty permits any.

`LifecycleConstraints`

Field	Type	Description
`default_lifetime_seconds`	`int32`	Lifetime applied when the sandbox requests none.

The policy carries no lifetime cap. The platform maximum of 30 days bounds every sandbox: a create request above it is rejected. The max_lifetime_seconds field was removed from the policy document, and cwic rejects a policy that still carries it.

`MetadataConstraints`

Field	Type	Description
`denied_annotation_prefixes`	`string` list	Annotation key prefixes that are rejected.
`max_annotation_count`	`int32`	Maximum annotations a sandbox may set. `0` means no limit.

`VolumeConstraints`

Field	Type	Description
`allowed_media`	`StorageMedium` list	Permitted storage media. Empty permits any.
`max_size`	`string`	Maximum size per volume, such as `100Gi`.

`StorageMedium`

Value	Description
`STORAGE_MEDIUM_UNSPECIFIED`	Invalid in `allowed_media`. On scratch-volume requests, omission or this value defaults to disk-backed storage.
`STORAGE_MEDIUM_DISK`	Disk-backed.
`STORAGE_MEDIUM_MEMORY`	RAM-backed, counting against the container’s memory.

To forbid RAM-backed volumes, set a non-empty allowed_media list containing only STORAGE_MEDIUM_DISK. An empty list permits any storage medium.

Validation rules

A policy is rejected when any of the following hold:

The encoded document exceeds 256 KiB.
The policy is null. A configured policy can’t be cleared, only replaced.
default_egress contains https_hostname rules.
Default egress or ingress rules fall outside the corresponding allowlist.
A source IP allowlist contains an invalid IPv4 or IPv6 CIDR, more than 256 entries, or more than 16 KiB of CIDR text.

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Top-level fields

Resolution order

`base`

`control_plane_access`

`SourceIpAllowlist`

`constraints`

`ResourceConstraints`

`ImageConstraints`

`NetworkConstraints`

`EgressRule`

`IngressRule`

`CidrBlock`

`PortRange`

`TenantScope`

`SelectorBlock`

`SecurityConstraints`

`RuntimeClassMapping`

`InstanceConstraints`

`LifecycleConstraints`

`MetadataConstraints`

`VolumeConstraints`

`StorageMedium`

Validation rules

See also

​Top-level fields

​Resolution order

​base

​control_plane_access

​SourceIpAllowlist

​constraints

​ResourceConstraints

​ImageConstraints

​NetworkConstraints

​EgressRule

​IngressRule

​CidrBlock

​PortRange

​TenantScope

​SelectorBlock

​SecurityConstraints

​RuntimeClassMapping

​InstanceConstraints

​LifecycleConstraints

​MetadataConstraints

​VolumeConstraints

​StorageMedium

​Validation rules

​See also

Top-level fields

Resolution order

`base`

`control_plane_access`

`SourceIpAllowlist`

`constraints`

`ResourceConstraints`

`ImageConstraints`

`NetworkConstraints`

`EgressRule`

`IngressRule`

`CidrBlock`

`PortRange`

`TenantScope`

`SelectorBlock`

`SecurityConstraints`

`RuntimeClassMapping`

`InstanceConstraints`

`LifecycleConstraints`

`MetadataConstraints`

`VolumeConstraints`

`StorageMedium`

Validation rules

See also