Profile reference - CoreWeave Docs

This page documents every field that cwic sandbox profile create -f and cwic sandbox profile edit accept in a sandbox profile. 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 following shape 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, CoreWeave Support, or email support@coreweave.com.

Top-level fields

The following fields appear at the root of a profile document.

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.
`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.

The server rejects output-only fields (id, organization_id, created_at, updated_at) on create.

Spec fields

The spec block defines the runtime shape every sandbox launched from this profile inherits. The following sections describe each subsection in detail.

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`. The service forwards this 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 and carry no authorization semantics.
`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. The service rejects overrides that exceed the organization’s per-sandbox resource quota.

`namespace`

Controls how the service places each sandbox 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 (up to 63 characters).
`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, and 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 the platform to assign an external IP 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 (for example, `nginx` or `istio`) 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. The service filters out reserved labels (such as `sandbox-id`).
`metadata.annotations`	map[string]string	Pod annotations. The service filters out reserved annotations.
`spec`	partial Kubernetes `PodSpec`	Any valid PodSpec fields including volumes, init containers, security context, and tolerations. The service merges these with sandbox-specific defaults. PodSpec inner field names follow Kubernetes camelCase (for example, `nodeSelector` and `securityContext`).
`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 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`.

Each edit replaces the runner’s profile_bindings list as a whole. The service detaches any binding omitted from the patch, so the patch must include every binding you want to keep, not just the ones you add or change. The service matches bindings by profile_template_id.

Validation rules

The control plane enforces the following rules when you create or edit a profile.

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: up to 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.
The service rejects payloads that mix 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.
The service rejects duplicate keys anywhere in the YAML payload.
You can’t delete a profile 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 in the preceding sections 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.

​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