Sandboxes architecture

This page describes how CoreWeave Sandboxes fit together, for administrators deploying runners, authoring a policy, or planning a multi-cluster rollout. CoreWeave sandboxes are built from two resources you manage (managed runner and sandbox), the policy each runner carries, 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 walkthrough that enables a runner and launches a sandbox, see Use your own compute. For how a sandbox resolves against a policy, see Policies overview.

​

Sandbox resources

• Managed runner: a CoreWeave-operated component that runs inside one of your CKS clusters. The runner places, supervises, and tears down sandboxes on that cluster. Each cluster hosts at most one managed runner, which CoreWeave keeps up to date on the RELEASE_CHANNEL_STABLE or RELEASE_CHANNEL_RAPID channel 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: an isolated workload that runs 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.

The gateway is not a resource you create or own. It is a CoreWeave service at 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. Once a sandbox is running, its data operations can also travel over a direct mTLS connection that bypasses the gateway. See Direct sandbox connections.

​

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 can supply a default sandbox lifetime; the platform enforces the 30-day maximum.
• 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. 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. For CKS placement, the gateway selects compute across clusters in your organization. Without a runner ID restriction, it selects a cluster with available capacity whose runner policy permits the sandbox request. 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 at api.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 the sandbox from the result. The runner accepts the placement as soon as it creates the sandbox, without waiting for it to start, so the client receives the sandbox ID while the sandbox is still starting. A successful start response means the runner accepted the sandbox, not that the sandbox can run commands yet. Before you use the sandbox, wait or poll until it reaches RUNNING. If startup fails, the sandbox moves to FAILED instead, and it can also reach COMPLETED before RUNNING if its main command exits quickly. Handle both terminal states. The Python SDK’s wait() polls for you, and operations such as exec() wait for RUNNING before they run. See Sandbox lifecycle. 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, subsequent client calls (exec, file operations, stop) flow through the gateway to the runner that owns the sandbox, and from there to the sandbox itself. Exec, log, and file operations can also bypass the gateway entirely. The Python SDK prefers a direct mTLS connection from the client to the sandbox and falls back to the gateway path shown above when direct access is unavailable. Lifecycle and management calls always use the gateway. See Direct sandbox connections.

​

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

• Use your own compute: enable 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.
• Protobuf: which host serves each service, and how to generate a client from the published Protobuf module.