CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, CoreWeave Support, or email support@coreweave.com.
Three pieces in play
This section introduces the three objects that determine a sandbox’s runtime shape. Understanding their roles is a prerequisite for the layering and update semantics that follow. 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 doesn’t 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, and 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 don’t 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’s 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 CoreWeave Intelligent CLI 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 can’t 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’re 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 CoreWeave Intelligent CLI steps, and the Control plane API overview for the REST field-mask contract.
When to split profiles compared to using overrides
The preceding layering and update rules leave room for two common problem patterns. Avoid both to keep the profile inventory maintainable as your fleet grows.- 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 isn’t 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: CoreWeave Intelligent CLI 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.