CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, CoreWeave Support, or email support@coreweave.com.
Sandbox resources
- Managed runner: a CoreWeave-operated component that runs 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. - Policy: what sandboxes on a cluster may request, and what they get by default. A policy is not a standalone resource and has no endpoint of its own: it is a field on the runner, so exactly one policy governs each cluster. To author one, see Configure a sandbox policy.
- Sandbox: the running pod on your cluster. A sandbox describes itself completely, declaring the image, compute, network access, and lifetime it needs. Sandboxes are created on demand through the Python client.
api.cwsandbox.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 connect to a runner directly.
Key constraints
- A cluster hosts at most one managed runner, and every runner carries exactly one policy. One policy therefore governs one cluster. To run sandboxes under a different posture, deploy a runner on another cluster and give it its own policy.
- A policy is required. An empty policy is valid and declares a fully permissive posture, so a cluster’s posture is always stated rather than inherited by accident.
- A policy must bound sandbox lifetime.
- Editing a policy affects sandboxes created after the edit. Running sandboxes keep the policy they resolved against at launch.
- There is no per-user or per-team scoping within a cluster. A policy applies to every sandbox placed there, whoever created it.
Resource relationships
The runner is the join. It carries the policy that governs its cluster, and it places every sandbox on that cluster. A sandbox states what it needs, and the policy decides whether that request is permitted. The runner merges the sandbox spec over the policy’s defaults, then validates the result against the constraints. A violation is rejected rather than quietly narrowed, and the error names what was refused. The one exception is sandbox lifetime, which is clamped to the policy maximum. Thebase defaults stage is not active yet. See Policies overview.
Multi-cluster scope
Each cluster has its own runner and its own policy. Users don’t need to know that topology: they ask the SDK for a sandbox with the configuration they need, and the gateway routes the request to a cluster whose policy accepts it. The gateway is scheduling-aware across every runner attached to your organization. A request without an explicit cluster lands on a runner whose policy permits what the sandbox asked for and whose capacity fits. Because posture is per cluster, a team that needs both a permissive environment and a restricted one runs two clusters rather than two configurations on one.How sandboxes launch
The resources move through two service surfaces. The control plane atapi.coreweave.com is where you define runners and the policy each one carries. The data plane at api.cwsandbox.com is where sandboxes are launched and operated. The split matters when you reason about failures and access control: a control-plane outage blocks runner and policy 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 the CoreWeave Intelligent CLI or the REST API to deploy a runner on a CKS cluster and set the policy it carries. 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 the policy. For the corresponding workflows, see Configure a sandbox policy and Deploy and manage a runner.Data plane: sandbox launch
When a client starts a sandbox, the gateway picks an eligible runner and sends it a placement request. The runner resolves the sandbox spec against its policy and creates a pod from the result. The rejection path is the one users notice. Because the error names the constraint that failed, a user who asks for something the cluster does not permit learns what to change or what to ask an administrator for, rather than having to discover the posture in advance.Data plane: running sandbox operations
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 resources
The control plane exposes runners as its administrative resource. A policy is reached through the runner that carries it, not through an endpoint of its own.
The Control plane API overview covers authentication, field masks, heartbeats, and the request and response shapes for these endpoints.
See also
- Get started: configure a policy, deploy a runner, and launch a sandbox.
- Policies overview: how a sandbox resolves against a policy.
- Configure a sandbox policy: every constraint group, with worked examples.
- Deploy and manage a runner: the lifecycle for managed runners.
- Control plane API overview: authentication, field masks, and the request and response shapes for every endpoint.