Sandboxes architecture

This page describes the architecture of CoreWeave Sandboxes for administrators and platform engineers who need to understand how the pieces fit together before deploying runners, authoring profiles, or planning a multi-cluster rollout. Read it to learn which resources you manage, which infrastructure CoreWeave operates, and how a sandbox request travels from the client to a pod on one of your clusters. 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 CoreWeave Intelligent CLI 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.

​

Sandbox resources

The following list summarizes the four user-managed resources. 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 ProfileTemplate resources, so SDK and REST fields use the profile_template_id name.
• 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_STABLE or RELEASE_CHANNEL_RAPID channel you select.
• Profile binding: the attachment between a profile and a runner, with an optional overrides_json partial spec that tweaks the profile for that one runner. Bindings live inside the runner object, and exactly one of a runner’s bindings must have is_default: true.
• Sandbox: the running pod on your cluster. Sandboxes are created on demand against a specific runner and profile through the Python client.

The gateway is not a resource you create or own. It is a CoreWeave service at 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 connect 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_json masks 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’s overrides_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 reach sandboxes that run across more than one CKS cluster, and the gateway hides that topology from clients. 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 don’t 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 following sections describe how the four resources move through two service surfaces, from one-time administrator setup to the runtime path a client takes when it starts and operates a sandbox. The four resources move through two service surfaces. The control plane at api.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 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 the CoreWeave Intelligent CLI 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. For the corresponding CoreWeave Intelligent CLI and REST workflows, see Configure a sandbox profile and Deploy and manage a runner.

​

Data plane: sandbox launch

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 any overrides_json, and creates a pod that matches the resolved spec.

​

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 resource families

The control plane API exposes two resource families. Profile bindings are mutated through the runner endpoint, not through their own. The Control plane API overview covers authentication, field masks, heartbeats, and the request and response shapes for these endpoints.

​

See also

• Get started: the CoreWeave Intelligent CLI 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 CoreWeave Intelligent CLI workflow for building profiles and managing bindings.
• Deploy and manage a runner: the CoreWeave Intelligent CLI 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.