> ## 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.

# Sandboxes architecture

> The four resources that build a sandbox, the control plane and data plane that operate it, and the multi-cluster topology that ties them together.

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](/products/sandboxes/get-started). For the deep dive on how profiles, bindings, and overrides combine when a sandbox launches, see [Understanding profiles](/products/sandboxes/profiles/profiles).

<Note>
  CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, [CoreWeave Support](https://cloud.coreweave.com/contact), or email [support@coreweave.com](mailto:support@coreweave.com).
</Note>

## Sandbox resources

The following list summarizes the four user-managed resources. The deeper interactions of profiles, bindings, and overrides live on [Understanding profiles](/products/sandboxes/profiles/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](/products/sandboxes/profiles/configure). 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](/products/sandboxes/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.

```mermaid theme={"system"}
graph LR
    P[Profile]
    B[Binding]
    O[overrides_json on binding]
    R[Managed runner]
    S[Sandbox]

    R -->|holds| B
    B -->|references| P
    B -.->|optionally masks fields of| O
    R -->|places| S
    P -->|shapes| S
    O -.->|tweaks shape for this runner| S
```

## 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.

```mermaid theme={"system"}
graph TB
    Client[Client / Python SDK]
    GW[Gateway]

    subgraph C3[CKS Cluster C]
        direction TB
        R3[Managed runner]
        S3A[sandbox]
        S3B[sandbox]
        R3 --> S3A
        R3 --> S3B
    end
    subgraph C2[CKS Cluster B]
        direction TB
        R2[Managed runner]
        S2A[sandbox]
        R2 --> S2A
    end
    subgraph C1[CKS Cluster A]
        direction TB
        R1[Managed runner]
        S1A[sandbox]
        S1B[sandbox]
        R1 --> S1A
        R1 --> S1B
    end

    Client --> GW
    GW <-->|mTLS| R1
    GW <-->|mTLS| R2
    GW <-->|mTLS| R3
```

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.

```mermaid theme={"system"}
sequenceDiagram
    participant Admin as cwic / REST API
    participant CP as Control plane<br/>api.coreweave.com
    participant Runner as Managed runner

    Admin->>CP: Create profile
    CP-->>Admin: profile_template_id
    Admin->>CP: Deploy runner with profile bindings
    CP-->>Runner: Deploy runner to cluster
    Runner-->>CP: Heartbeat (connected, ready)
```

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](/products/sandboxes/profiles/configure) and [Deploy and manage a runner](/products/sandboxes/operations/managed-runners).

### 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.

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Python SDK / REST API
    participant GW as Gateway<br/>atc.cw-sandbox.com
    participant Runner as Managed runner
    participant Pod as Sandbox pod

    Client->>GW: StartSandbox (profile_name optional)
    GW->>GW: Scheduler picks an eligible runner
    GW->>Runner: PlacementRequest
    Runner->>Runner: Resolve binding + overrides
    Runner->>Pod: Create pod from resolved spec
    Pod-->>Runner: Ready
    Runner-->>GW: PlacementResponse (sandbox_id)
    GW-->>Client: sandbox_id
```

### 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.

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Python SDK / REST API
    participant GW as Gateway<br/>atc.cw-sandbox.com
    participant Runner as Owning runner
    participant Pod as Sandbox pod

    Client->>GW: Exec, file ops, stop
    GW->>Runner: Forward to sandbox owner
    Runner->>Pod: Apply
    Pod-->>Runner: Result
    Runner-->>GW: Response
    GW-->>Client: Response
```

## 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.                                                 |

The [Control plane API overview](/products/sandboxes/reference/control-plane-api) covers authentication, field masks, heartbeats, and the request and response shapes for these endpoints.

## See also

* [Get started](/products/sandboxes/get-started): the CoreWeave Intelligent CLI walkthrough that creates a profile, deploys a runner, and launches a sandbox.
* [Understanding profiles](/products/sandboxes/profiles/profiles): how profiles, bindings, and overrides combine at sandbox launch.
* [Configure a sandbox profile](/products/sandboxes/profiles/configure): the CoreWeave Intelligent CLI workflow for building profiles and managing bindings.
* [Deploy and manage a runner](/products/sandboxes/operations/managed-runners): the CoreWeave Intelligent CLI and REST lifecycle for managed runners.
* [Control plane API overview](/products/sandboxes/reference/control-plane-api): authentication, field masks, and the request and response shapes for every endpoint.
* [Profile reference](/products/sandboxes/reference/profile): the full profile schema.