Profile reference

This page documents every field in a sandbox profile as accepted by cwic sandbox profile create -f and cwic sandbox profile edit. The control-plane API names the persisted resource ProfileTemplate; the CLI exposes the same concept under cwic sandbox profile, so “profile” and “profile template” refer to the same thing throughout the documentation. For task-oriented configuration help, see Configure a sandbox profile. The shape below is the structured YAML the CoreWeave Intelligent CLI accepts as input and renders for editing. The control plane stores three sub-blocks (spec.namespace, spec.network, spec.pod) as JSON-encoded strings; the CLI translates between the two at the client boundary. See Wire format mapping.

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, reach out to CoreWeave Support, or email [email protected].

Top-level fields

Field	Type	Required	Description
`display_name`	string	yes	Unique within the organization. Reused as the default `profile_name` in bindings that omit one.
`description`	string	no	Free-form description.
`id`	string (UUID)	no	Server-assigned on create. Rejected if set in a create payload. In `cwic sandbox profile edit [PROFILE-ID] -f`, omit it or set it to the same value as the positional profile ID.
`labels`	map[string]string	no	Free-form labels for organization. No runtime semantics today.
`spec`	`ProfileSpec`	yes	Profile shape. Must be present on create; an empty `spec: {}` is allowed and produces sandboxes that inherit every field from the runner’s zone defaults.

Output-only fields populated by the server (id, organization_id, created_at, updated_at) are rejected on create.

Spec fields

spec:
  container_image: ghcr.io/myorg/python:3.11
  resource_defaults: {...}
  instance_types: [h100]
  node_selector: {gpu: h100}
  tags: [ml]
  namespace: {...}
  network: {...}
  pod: {...}

Field	Type	Description
`container_image`	string	Container image reference. Inherits the runner’s zone default when unset.
`runtime_class`	string	Kubernetes `runtimeClassName`. Forwarded verbatim to the sandbox pod; you can use any `RuntimeClass` you have installed and registered on the target CKS cluster. Leave unset to use the node default (typically `runc`). Missing classes surface at sandbox-schedule time, not at profile validation.
`resource_defaults`	`ResourceDefaults`	Default CPU and memory requests and limits.
`instance_types`	string[]	Restricts sandboxes to specific CoreWeave instance classes. Expands to a node-affinity constraint.
`node_selector`	map[string]string	Kubernetes `nodeSelector` labels applied to every sandbox pod.
`tags`	string[]	Free-form tags for organization. Tags are descriptive; they carry no authorization semantics today.
`namespace`	`NamespaceConfig`	Namespace strategy.
`network`	`NetworkConfig`	Egress and ingress policy.
`pod`	`PodTemplate`	Partial Kubernetes PodSpec plus pod metadata.

All spec fields are optional.

`ResourceDefaults`

Default Kubernetes resource requests and limits. Values use standard Kubernetes quantity syntax.

Field	Type	Example	Description
`cpuRequest`	string	`500m`	Default CPU request.
`memoryRequest`	string	`1Gi`	Default memory request.
`cpuLimit`	string	`"2"`	Default CPU limit.
`memoryLimit`	string	`4Gi`	Default memory limit.

Sandboxes can override these at launch. Overrides are rejected if they exceed the organization’s per-sandbox resource quota.

`namespace`

Controls how each sandbox is placed into a Kubernetes namespace.

spec:
  namespace:
    strategy: per-user
    namespacePrefix: sb-
    autoCreate: true
    staticNamespace: ""
    labels: {team: ml}
    annotations: {}

Field	Type	Default	Description
`strategy`	enum string	`per-user`	One of `per-user`, `per-org`, `per-profile`, `static`. Empty defaults to `per-user`.
`staticNamespace`	string	none	Required when `strategy: static`. Must be a valid DNS-1123 label (≤63 chars).
`namespacePrefix`	string	`""`	Prepended to auto-generated namespace names. Keep short; namespace names are capped at 63 characters.
`autoCreate`	bool	`true`	Whether the service creates the namespace on first use. Set to `false` when namespaces are provisioned externally.
`labels`	map[string]string	none	Applied to auto-created namespaces.
`annotations`	map[string]string	none	Applied to auto-created namespaces.

Strategies

Value	Namespace per
`per-user`	(organization, user)
`per-org`	Organization
`per-profile`	Profile
`static`	Cluster-wide (all sandboxes share `staticNamespace`)

`network`

Controls outbound (egress) and inbound (ingress) traffic for sandboxes launched from the profile.

spec:
  network:
    egress: {...}
    ingress: {...}

When network is omitted entirely, sandboxes default to no outbound connectivity and no exposed ports.

`network.egress`

egress:
  default: internet
  modes:
    internet: {type: internet}
    allow: {type: allowlist, cidrs: ["10.0.0.0/8"]}

Field	Type	Description
`default`	string	Name of the mode sandboxes get when they don’t specify one. Required when `modes` defines more than one mode. With a single mode, `default` may be omitted; that mode is used. When set, the value must reference a key in `modes`.
`modes`	map[string]`EgressMode`	Named modes available to sandboxes at launch. When `egress` is present, `modes` must contain at least one entry.

`EgressMode`

Field	Type	Required	Description
`type`	enum string	yes	One of `internet`, `allowlist`, `org`, `user`, `profile`, `none`.
`cidrs`	string[]	when `type: allowlist`	CIDR ranges allowed for outbound. Each entry must parse as a valid CIDR.

Egress types

Type	Allows outbound to
`internet`	The public internet.
`allowlist`	Only the CIDR ranges in `cidrs`.
`org`	Other sandboxes in the same organization.
`user`	Other sandboxes owned by the same user.
`profile`	Other sandboxes using the same profile.
`none`	Nothing.

`network.ingress`

Keyed by exposure level name. Common names are internal and public. Any non-empty string is accepted except none, which is reserved.

ingress:
  internal:
    scope: org
    service: {serviceType: ClusterIP}
  public:
    scope: any
    expectsExternalAddress: true
    service: {serviceType: LoadBalancer}
    ingress:
      controllerName: nginx
      template: "{{.SandboxID}}.example.com"

`IngressLevel`

Field	Type	Default	Description
`scope`	enum string	`any`	Who can reach the exposure. One of `user`, `profile`, `org`, `any`.
`expectsExternalAddress`	bool	`false`	When `true`, sandboxes wait for an external IP to be assigned before becoming ready.
`service`	`ServiceConfig`	none	Kubernetes Service strategy.
`ingress`	`IngressConfig`	none	Ingress resource strategy in front of the service.

`ServiceConfig`

Field	Type	Description
`serviceType`	string	One of `ClusterIP`, `NodePort`, `LoadBalancer`. Maps directly to a Kubernetes Service type.
`serviceSelectorAnnotation`	`AnnotationPair`	Annotation to pin address-pool selection (for example, MetalLB).
`dnsAnnotation`	`AnnotationPair`	Annotation for an external DNS controller (for example, ExternalDNS).

`IngressConfig`

Field	Type	Description
`controllerName`	string	Ingress controller name (`nginx`, `istio`, etc.) on the target cluster.
`template`	string	Go-template hostname. Variables: `{{.SandboxID}}`, `{{.Namespace}}`.

`AnnotationPair`

Field	Type	Description
`key`	string	Annotation key.
`value`	string	Annotation value.

`pod`

A partial Kubernetes PodSpec plus pod metadata and placement hints. Use this for fields the structured profile shape does not model.

spec:
  pod:
    metadata:
      labels: {app: agent}
      annotations: {owner: ml-platform}
    spec:
      volumes: [...]
      initContainers: [...]
      securityContext: {runAsNonRoot: true}
    placement:
      instanceTypes: [h100]

Field	Type	Description
`metadata.labels`	map[string]string	Pod labels. Reserved labels (such as `sandbox-id`) are filtered out by the service.
`metadata.annotations`	map[string]string	Pod annotations. Reserved annotations are filtered out.
`spec`	partial Kubernetes `PodSpec`	Any valid PodSpec fields including volumes, init containers, security context, tolerations. Merged with sandbox-specific defaults. PodSpec inner field names follow Kubernetes camelCase (`nodeSelector`, `securityContext`, etc.).
`placement.instanceTypes`	string[]	Equivalent to top-level `spec.instance_types`. Use either, not both.

If you only need to pin instance types or set a runtime class, prefer the top-level fields. Reserve spec.pod for cases that genuinely need PodSpec depth. A profile binding attaches a profile to a runner so the runner enforces that profile’s policies and guardrails for sandboxes it places. Bindings live in the runner object’s top-level profile_bindings list, not as standalone resources. They are managed with cwic sandbox runner edit.

Field	Type	Required	Description
`profile_template_id`	string (UUID)	yes	The ID of the profile this binding references. The field name retains the legacy `_template_` suffix from the on-wire schema.
`profile_name`	string	no	Alias sandboxes use to pick this profile at launch. Falls back to the profile’s `display_name` when omitted.
`is_default`	bool	no	Whether this binding is the fallback when a sandbox does not specify a profile. Exactly one binding per runner must be `true`.

The runner’s profile_bindings list is replaced as a whole on each edit. Any binding omitted from the patch is detached from the runner, so the patch must include every binding you want to keep, not just the ones being added or changed. Matching is by profile_template_id.

Validation rules

display_name must be unique within the organization. Conflicts surface as an AlreadyExists error.
staticNamespace and any generated namespace name must satisfy DNS-1123 label rules: ≤63 characters, lowercase alphanumeric, hyphens allowed, no leading or trailing hyphens.
When network.egress is present, egress.modes must contain at least one mode.
egress.default is required when egress.modes defines more than one mode. When set, it must reference a key present in modes.
Each entry in an allowlist mode’s cidrs must parse as a valid CIDR.
resource_defaults values must parse as Kubernetes resource quantities.
runtime_class, when set, is only verified at sandbox-schedule time. A profile referencing a runtime class that isn’t installed on the target cluster fails at sandbox launch, not at profile validation.
Mixing a structured key (spec.namespace, spec.network, spec.pod) with its proto alias (spec.namespace_config_json, spec.network_config_json, spec.pod_template_json) at the same path is rejected.
Duplicate keys anywhere in the YAML payload are rejected.
A profile cannot be deleted while it is bound to a runner. Detach the binding with cwic sandbox runner edit before retrying the delete.

Wire format mapping

The CoreWeave Intelligent CLI accepts the structured shape documented above and rewrites three sub-blocks to JSON-encoded string fields before sending to the control plane. Both forms are valid input. cwic sandbox profile edit renders the structured form so you don’t have to hand-edit escaped JSON strings; cwic sandbox profile get -o json returns the proto-facing shape with the JSON-encoded sub-blocks intact.

Structured key	Proto-facing alias
`spec.namespace`	`spec.namespace_config_json`
`spec.network`	`spec.network_config_json`
`spec.pod`	`spec.pod_template_json`

Tools that talk to the control plane directly (for example, generated SDK clients) see the proto-facing aliases. CoreWeave Intelligent CLI users do not need to construct these strings manually.

Profiles

Reference

Python Client

Top-level fields

Spec fields

`ResourceDefaults`

`namespace`

Strategies

`network`

`network.egress`

`EgressMode`

Egress types

`network.ingress`

`IngressLevel`

`ServiceConfig`

`IngressConfig`

`AnnotationPair`

`pod`

Validation rules

Wire format mapping

See also

Profiles

Reference

Python Client

Documentation Index

​Top-level fields

​Spec fields

​ResourceDefaults

​namespace

​Strategies

​network

​network.egress

​EgressMode

​Egress types

​network.ingress

​IngressLevel

​ServiceConfig

​IngressConfig

​AnnotationPair

​pod

​Related runner field: profile_bindings

​Validation rules

​Wire format mapping

​See also

Top-level fields

Spec fields

`ResourceDefaults`

`namespace`

Strategies

`network`

`network.egress`

`EgressMode`

Egress types

`network.ingress`

`IngressLevel`

`ServiceConfig`

`IngressConfig`

`AnnotationPair`

`pod`

Related runner field: `profile_bindings`

Validation rules

Wire format mapping

See also