A profile defines which resources and capabilities a sandbox can request: container image, runtime class, compute shape, namespace, ingress and egress, and pod placement. Profiles serve as guardrails administrators use to enforce policies such as “sandboxes cannot have internet egress” or “sandboxes can request up to N CPUs and M GB of memory.” When a sandbox launches, the runner that places it resolves a single profile and uses it to shape the pod it creates. This page is conceptual. It explains how profiles, profile bindings, and overrides combine at sandbox launch, why profile updates behave the way they do, and when to use bindings with overrides versus separate profiles. For the cwic workflow and a field-by-field walkthrough, see Configure a sandbox profile. For the full schema with types and defaults, see the Profile reference.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.
CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, reach out to CoreWeave Support, or email support@coreweave.com.
Three pieces in play
Three objects shape a sandbox’s spec at launch:- Profile: the stored, organization-wide configuration that defines what a sandbox can request.
- Binding: the link between a profile and a runner, with optional per-runner overrides.
- Override: a partial profile spec on a single binding that tweaks the profile for that one runner.
| Field | Purpose |
|---|---|
profile_template_id | The profile being referenced (UUID). |
profile_name | An optional alias sandboxes use to select the profile at launch, instead of the profile’s display_name. |
is_default | Whether this binding is the fallback when a sandbox does not specify a profile. Exactly one binding per runner must be true. |
overrides_json | A partial profile spec, JSON-encoded as a string, that overrides specific fields of the referenced profile for sandboxes placed on this runner. |
Mental model: the profile is the source of truth for sandbox shape; a binding attaches that profile to a specific runner; an override on a binding tweaks the profile for that one runner without forking a new profile.
How fields combine at runtime
When a sandbox launches, the service resolves its configuration by layering four sources. The layers are applied in order, and when two layers set the same field, the later layer wins. Layer 4 has the final word; layer 1 only shows through for fields nothing above it sets. The resolved spec is submitted to Kubernetes as the sandbox pod.| Applied | Layer | Source | Overrides |
|---|---|---|---|
| 1st (lowest precedence) | Runner zone defaults | Baseline applied by the runner before anything else. | nothing |
| 2nd | Profile spec | The stored profile attached by the binding. | layer 1 |
| 3rd | Binding overrides_json | Partial profile spec on this binding, scoped to one runner. | layers 1-2 |
| 4th (highest precedence) | Per-sandbox overrides | Fields supplied by the caller at launch. | layers 1-3 |
node_selector leaves every other field of the profile intact. You do not need to duplicate the full profile spec in an override. Supply only the fields that differ.
Update semantics
Three behaviors shape what happens when you change a profile or binding that real traffic depends on. Knowing them up front lets you predict the impact of an edit before you make it.- Profile updates are immediate and fleet-wide. Every runner with a binding to the profile picks up the new spec for the next sandbox it places. The runner resolves the binding to a profile each time a sandbox launches against it, so there is no staged rollout and no concept of profile revisions on the server. If you need staged rollout, version the profile by name (
agent-v1,agent-v2) and migrate runners one binding at a time. See Update an existing profile for the cwic steps. - Running sandboxes are unaffected. A sandbox uses the spec it was launched with. New sandboxes pick up the new spec. This decoupling is what makes profile updates safe to apply at any time; the cost is that you cannot retroactively reshape sandboxes already running.
- Binding edits replace the full list. A runner’s
profile_bindingsis patched as a single list. Whatever you submit becomes the new list, so any binding you don’t include is removed. The patch must contain every binding you want to keep, not just the ones you are adding or changing, and the resulting list must still have exactly oneis_default: true. This is what lets the control plane apply adds, removes, and changes atomically. Thecwic sandbox runner editwizard handles list assembly for you when you run it without-f. See Manage profile bindings for the cwic steps, and the Control plane API overview for the REST field-mask contract.
When to split profiles versus use overrides
Two anti-patterns worth avoiding:- Per-runner profile sprawl. When two profiles differ by only one field (commonly the
node_selectorthat pins sandboxes to a region or instance type), the duplication makes the profile harder to evolve. Consolidate into a single profile and set the differing field withoverrides_jsonon each binding. For example, instead of separateagent-useast,agent-euwest, andagent-apacprofiles, keep oneagentprofile and override the node selector per runner. - Overrides that fork the spec. If a binding’s
overrides_jsonis larger than the profile’s spec, the profile is not doing work for you. Promote the override into a dedicated profile.
See also
- Sandboxes architecture: the four-resource taxonomy and the gateway that brokers runtime requests.
- Configure a sandbox profile: cwic workflow plus the field-by-field walkthrough of the profile spec.
- Profile examples: ready-to-POST profile templates and runner bindings for common use cases.
- Control plane API overview: authentication, field masks, heartbeats, and the endpoint contract.
- Profile reference: the full schema with types, defaults, and validation rules.