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

# Sandbox placement and spillover

> Compare serverless and CKS sandboxes, select where they run, and configure fallback between modes.

Placement determines which compute runs your sandbox. Serverless uses CoreWeave-managed compute. Cluster placement uses compute in a CoreWeave Kubernetes Service (CKS) cluster in your organization. Spillover retries sandbox creation in the other mode when the initial placement fails.

## Compare placement modes

Choose a mode based on who manages the capacity and policy:

|                           | Serverless                                       | CKS                                                                                                            |
| ------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Where sandboxes run       | CoreWeave-managed compute                        | Compute in your CKS cluster                                                                                    |
| Who configures the policy | CoreWeave                                        | Your administrators                                                                                            |
| Setup                     | Authenticate with a W\&B or CoreWeave credential | Enable a runner on the cluster                                                                                 |
| Placement control         | Platform-managed. You don't select a cluster.    | Python can use any eligible cluster; specify runner IDs to restrict placement. TypeScript requires runner IDs. |
| Resources                 | Choose CPU and memory for each sandbox           | Choose CPU and memory within your cluster's policy                                                             |
| Credentials               | W\&B API key or CoreWeave API access token       | CoreWeave API access token                                                                                     |
| When to use it            | Run sandboxes without managing cluster capacity  | Use your cluster's capacity and control resource and network policies                                          |

Follow the [serverless quickstart](/products/sandboxes/get-started) or [Use your own compute](/products/sandboxes/get-started-cks) to create your first sandbox.

## Choose and get credentials

Your credential determines which account owns the sandbox and is billed for its usage. W\&B API keys support serverless sandboxes. CoreWeave API access tokens support both serverless and cluster sandboxes.

### W\&B API key

Choose W\&B if you don't have a CoreWeave console account or prefer W\&B billing:

1. Open [wandb.ai/authorize](https://wandb.ai/authorize). Sign in, or create an account through the same link.
2. Copy your API key and set it in the terminal where you run the client:

   ```bash theme={"system"}
   export WANDB_API_KEY="[WANDB-API-KEY]"
   ```

The examples use a key from wandb.ai. In Python, install `cwsandbox[wandb]` and select `AuthStrategy.WANDB`. In TypeScript, import the client from `@coreweave/cwsandbox/wandb`. The [serverless quickstart](/products/sandboxes/get-started) includes complete examples for both languages.

### CoreWeave API access token

Choose CoreWeave to use your CoreWeave organization's billing or run sandboxes on its cluster:

1. Ask your administrator to create or update an [Access Policy](https://console.coreweave.com/organization/iam/access-policies) granting you the **Sandbox User** role to run sandboxes. Administrators who enable runners and configure their policies need **Sandbox Admin**, which includes sandbox execution permissions. See [Create an access policy](/security/iam/access-policies/manage#create-an-access-policy) and [Sandbox roles](/security/iam/access-policies/roles#sandbox).
2. On the [Tokens](https://console.coreweave.com/tokens) page, click **Create Token**, complete the token details, and click **Create**.
3. Copy the **Token Secret** and set it in the terminal where you run the client:

   ```bash theme={"system"}
   export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
   ```

If you can't create a token, ask your administrator for the **Access Token Admin** role. The token secret is shown only once. For more information, see [Manage API access tokens](/security/authn-authz/manage-api-access-tokens). In Python, select `AuthStrategy.COREWEAVE_API_KEY`. In TypeScript, import the client from `@coreweave/cwsandbox/node`.

## Select a placement mode

Both Python and TypeScript support serverless and cluster placement. Serverless is the default. The [`PlacementMode` reference](/products/sandboxes/client/ref/workload/placement#placementmode) lists the supported mode values. Select cluster placement explicitly:

<Tabs>
  <Tab title="Python">
    Use `placement_mode="cks"`. Add `runner_ids` to restrict placement to particular runners:

    ```python theme={"system"}
    from cwsandbox import AuthStrategy, Sandbox

    with Sandbox.run(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=["[RUNNER-ID]"],
        resources={"cpu": "1", "memory": "1Gi"},
    ) as sandbox:
        print(sandbox.exec(["echo", "Hello!"]).result().stdout)
    ```

    Without `runner_ids`, CKS placement can use any eligible runner in your organization. For serverless, omit both fields or set `placement_mode="serverless"` without `runner_ids`.
  </Tab>

  <Tab title="TypeScript">
    Use the CoreWeave entry point and a nonempty `runnerIds` array to select CKS placement:

    ```typescript theme={"system"}
    import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

    const client = createSandboxClientFromEnv();
    const result = await client.withSandbox(
      async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
      {
        runnerIds: ["[RUNNER-ID]"],
        resources: { cpu: "1", memory: "1Gi" },
      },
    );
    console.log(result.stdout);
    ```

    Omit `runnerIds` for serverless placement.
  </Tab>
</Tabs>

Both cluster examples read `CWSANDBOX_API_KEY`. Complete [credential setup](#coreweave-api-access-token), then follow [Use your own compute](/products/sandboxes/get-started-cks) to enable a runner or the [serverless quickstart](/products/sandboxes/get-started) to install the TypeScript client.

## Spill over between modes

Automatic spillover is available in the Python client. The TypeScript client supports selecting either placement mode, but doesn't provide automatic spillover.

Spillover retries sandbox creation once in the alternate mode for eligible placement failures, such as unavailable capacity or no suitable runner. It doesn't move a running sandbox between modes.

Use a CoreWeave API access token for an organization with both serverless access and a configured CKS runner. A W\&B key alone doesn't provide CKS access.

To prefer CKS and fall back to serverless, set `placement_spillover="cks_then_serverless"`:

```python theme={"system"}
from cwsandbox import AuthStrategy, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_spillover="cks_then_serverless",
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    print(sandbox.exec(["echo", "Hello!"]).result().stdout)
```

The example specifies CPU and memory for both attempts. Each mode applies its own policy, so a request must satisfy the policy of the mode where it runs.

Set `placement_spillover` to one of the following options to control fallback:

| Option                | First attempt               | Fallback   | Constraints                                                                              |
| --------------------- | --------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
| `strict` (default)    | The selected placement mode | None       | Required when creating from a template or with `run_from_file()`                         |
| `cks_then_serverless` | CKS                         | Serverless | `placement_mode` must be `"cks"` or omitted                                              |
| `serverless_then_cks` | Serverless                  | CKS        | `placement_mode` must be `"serverless"` or omitted. Can't be combined with `runner_ids`. |

For the supported fallback values, see the [`PlacementSpillover` reference](/products/sandboxes/client/ref/workload/placement#placementspillover). For resource and timeout settings, see [Sandbox configuration](/products/sandboxes/client/guides/sandbox-configuration).


## Related topics

- [Get started with serverless sandboxes](/products/sandboxes/get-started.md)