CoreWeave sandboxes are built from four resources you manage (profile, managed runner, profile binding, and sandbox) and one piece of CoreWeave-operated infrastructure (the gateway) that brokers every sandbox request. The pieces live behind two service surfaces, a control plane for configuration and a data plane for traffic, and span as many CKS clusters as you choose to enable. For the cwic walkthrough that creates a profile, deploys a runner, and launches a sandbox, see Get started. For the deep dive on how profiles, bindings, and overrides combine when a sandbox launches, see Understanding profiles.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.
Sandbox resources
The four user-managed resources, with one line each. The deeper interactions of profiles, bindings, and overrides live on Understanding profiles.- Profile: an organization-wide configuration that defines what a sandbox can request, including container image, runtime class, compute shape, namespace, ingress and egress, and pod placement. Profiles are stored in the control plane and identified by a UUID. To author one, see Configure a sandbox profile. The API stores them as
ProfileTemplateresources, so SDK and REST fields use theprofile_template_idname. - Managed runner: a CoreWeave-operated component running inside one of your CKS clusters. The runner places, supervises, and tears down sandbox pods on that cluster. Each cluster hosts at most one managed runner, which CoreWeave keeps up to date on the
RELEASE_CHANNEL_STABLEorRELEASE_CHANNEL_RAPIDchannel you select. - Profile binding: the attachment between a profile and a runner, with an optional
overrides_jsonpartial spec that tweaks the profile for that one runner. Bindings live inside the runner object, and exactly one of a runner’s bindings must haveis_default: true. - Sandbox: the running pod on your cluster. Sandboxes are created on demand against a specific runner and profile through the Python client.
atc.cw-sandbox.com that authenticates every client call, picks an eligible runner to host the sandbox, and forwards traffic between the client and the runner that owns each sandbox. Clients never speak to a runner directly.
Key constraints
- A profile belongs to the organization. A runner belongs to a specific cluster. A binding lives on a runner and is not addressable on its own.
- A runner must have at least one binding, and exactly one of its bindings must be
is_default: true. - A cluster hosts at most one managed runner. To run sandboxes across more capacity, deploy a runner on another cluster.
- Editing a profile affects every runner with a binding to it, unless a binding’s
overrides_jsonmasks the field that changed.
Resource relationships
A binding is the join between a profile and a runner. The runner uses the binding to look up the profile, applies the binding’soverrides_json on top, and shapes the sandbox from the resolved spec. The result is a clean fan-out: many runners can bind a single profile, and a single runner can bind many profiles.
Multi-cluster scope
A single profile can be bound to runners on any of your CKS clusters, and the gateway is the single entry point for clients. Researchers do not need to know the cluster topology: they ask the SDK for a sandbox, optionally specifying a profile, and the gateway routes the request to whichever cluster has a runner that can host it. The gateway is scheduling-aware across every runner attached to your organization. A request without an explicit cluster lands on the runner that best matches the requested profile and resources.How sandboxes launch
The four resources move through two service surfaces. The control plane atapi.coreweave.com is where you describe profiles (what sandboxes can look like) and which runners exist; the data plane at atc.cw-sandbox.com is where sandboxes are actually launched and operated. The split matters when you reason about failures and access control: a control-plane outage blocks profile and runner edits but does not affect sandboxes already running, while a data-plane outage affects in-flight sandbox traffic but does not touch the configuration stored in the control plane.
Control plane: one-time setup
An administrator uses cwic or the REST API to create profiles, deploy a runner on a CKS cluster, and bind profiles to it. The control plane then deploys the runner into the cluster, and the runner reports back over its heartbeat. This step happens once per cluster, then again whenever you change profiles or bindings. The corresponding cwic and REST workflows are documented in Configure a sandbox profile and Deploy and manage a runner.Data plane: launching a sandbox
When a client starts a sandbox, the gateway picks an eligible runner, sends it a placement request, and returns the sandbox ID to the caller. The runner resolves the binding to a profile, applies anyoverrides_json, and creates a pod that matches the resolved spec.
Data plane: operating a running sandbox
Once a sandbox is placed, every subsequent client call (exec, file operations, stop) flows through the gateway to the runner that owns the sandbox, and from there to the pod itself.
Control plane resource families
The control plane API exposes two resource families. Profile bindings are mutated through the runner endpoint, not through their own.| Family | Endpoints | Purpose |
|---|---|---|
| Managed runners | POST/GET/PATCH/DELETE /v1beta2/sandbox/managed-runners, POST .../apply-update | Deploy, query, update, and decommission runners; trigger on-demand runner updates. |
| Profile templates | POST/GET/PATCH/DELETE /v1beta2/sandbox/profile-templates | Create, list, and evolve profiles. |
See also
- Get started: the cwic walkthrough that creates a profile, deploys a runner, and launches a sandbox.
- Understanding profiles: how profiles, bindings, and overrides combine at sandbox launch.
- Configure a sandbox profile: the cwic workflow for building profiles and managing bindings.
- Deploy and manage a runner: the cwic and REST lifecycle for managed runners.
- Control plane API overview: authentication, field masks, and the request and response shapes for every endpoint.
- Profile reference: the full profile schema.