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

> How runners, policies, and the gateway fit together across one or more CKS clusters.

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 configures a policy, deploys a runner, and launches a sandbox, see [Get started](/products/sandboxes/get-started). For how a sandbox resolves against a policy, see [Policies overview](/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

* **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.
* **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](/products/sandboxes/profiles/configure).
* **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](/products/sandboxes/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. 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.

```mermaid theme={"system"}
graph LR
    R[Managed runner]
    PL[Policy on the runner]
    S[Sandbox spec]
    P[Sandbox pod]

    R -->|carries| PL
    S -->|declares what it needs| PL
    PL -->|allows or rejects, then shapes| P
    R -->|places| P
```

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. The `base` defaults stage is not active yet. See [Policies overview](/products/sandboxes/profiles/profiles#how-a-sandbox-resolves-against-a-policy).

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

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

    subgraph C3[CKS Cluster C]
        direction TB
        R3[Managed runner + policy]
        S3A[sandbox]
        S3B[sandbox]
        R3 --> S3A
        R3 --> S3B
    end
    subgraph C2[CKS Cluster B]
        direction TB
        R2[Managed runner + policy]
        S2A[sandbox]
        R2 --> S2A
    end
    subgraph C1[CKS Cluster A]
        direction TB
        R1[Managed runner + policy]
        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 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** 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.

```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: Deploy runner on a cluster
    CP-->>Runner: Deploy runner to cluster
    Runner-->>CP: Heartbeat (connected, ready)
    Admin->>CP: Set the runner's policy
    CP-->>Admin: Updated runner
```

This step happens once per cluster, then again whenever you change the policy. For the corresponding workflows, see [Configure a sandbox policy](/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 and sends it a placement request. The runner resolves the sandbox spec against its policy and creates a pod from the result.

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

    Client->>GW: StartSandbox (spec)
    GW->>GW: Scheduler picks an eligible runner
    GW->>Runner: PlacementRequest
    Runner->>Runner: Merge spec with policy defaults, check constraints
    alt Request fits the policy
        Runner->>Pod: Create pod from resolved spec
        Pod-->>Runner: Ready
        Runner-->>GW: PlacementResponse (sandbox_id)
        GW-->>Client: sandbox_id
    else Request violates a constraint
        Runner-->>GW: Rejected, with the constraint that failed
        GW-->>Client: Error naming what was refused
    end
```

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.

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Python SDK / REST API
    participant GW as Gateway<br/>api.cwsandbox.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 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.

| Resource        | Endpoints                                                                           | Purpose                                                                                                             |
| --------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Managed runners | `POST/GET/PATCH/DELETE /v1/sandbox/managedRunners`, `POST .../applyAvailableUpdate` | Deploy, query, update, and decommission runners. Set the policy a runner carries. Trigger on-demand runner updates. |

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): configure a policy, deploy a runner, and launch a sandbox.
* [Policies overview](/products/sandboxes/profiles/profiles): how a sandbox resolves against a policy.
* [Configure a sandbox policy](/products/sandboxes/profiles/configure): every constraint group, with worked examples.
* [Deploy and manage a runner](/products/sandboxes/operations/managed-runners): the 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.