> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Profile reference
> Field-by-field schema for the profile YAML accepted by cwic sandbox profile commands.
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](/products/sandboxes/profiles/configure).
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](#wire-format-mapping).
CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, [CoreWeave Support](https://cloud.coreweave.com/contact), or email [support@coreweave.com](mailto: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`](#spec-fields) | 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.
```yaml theme={"system"}
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`](https://kubernetes.io/docs/concepts/containers/runtime-class/) 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`](#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) | Namespace strategy. |
| `network` | [`NetworkConfig`](#network) | Egress and ingress policy. |
| `pod` | [`PodTemplate`](#pod) | Partial Kubernetes PodSpec plus pod metadata. |
All spec fields are optional.
## `ResourceDefaults`
Default Kubernetes resource requests and limits. Values use standard Kubernetes [quantity syntax](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
| 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.
```yaml theme={"system"}
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.
```yaml theme={"system"}
spec:
network:
egress: {...}
ingress: {...}
```
When `network` is omitted entirely, sandboxes default to no outbound connectivity and no exposed ports.
### `network.egress`
```yaml theme={"system"}
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.
```yaml theme={"system"}
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`](#serviceconfig) | none | Kubernetes Service strategy. |
| `ingress` | [`IngressConfig`](#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`](#annotationpair) | Annotation to pin address-pool selection (for example, MetalLB). |
| `dnsAnnotation` | [`AnnotationPair`](#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.
```yaml theme={"system"}
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.
## Related runner field: `profile_bindings`
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.
## See also
* [Configure a sandbox profile](/products/sandboxes/profiles/configure) for task-oriented examples.
* [Get started](/products/sandboxes/get-started) for the end-to-end setup walkthrough.