Sandbox placement and spillover

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 or Use your own compute 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:

Open wandb.ai/authorize. Sign in, or create an account through the same link.
Copy your API key and set it in the terminal where you run the client:
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 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:

Ask your administrator to create or update an Access Policy 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 and Sandbox roles.
On the Tokens page, click Create Token, complete the token details, and click Create.
Copy the Token Secret and set it in the terminal where you run the client:
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. 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 lists the supported mode values. Select cluster placement explicitly:

Python
TypeScript

Use placement_mode="cks". Add runner_ids to restrict placement to particular runners:

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.

Use the CoreWeave entry point and a nonempty runnerIds array to select CKS placement:

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.

Both cluster examples read CWSANDBOX_API_KEY. Complete credential setup, then follow Use your own compute to enable a runner or the serverless quickstart 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":

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. For resource and timeout settings, see Sandbox configuration.

​Compare placement modes

​Choose and get credentials

​W&B API key

​CoreWeave API access token

​Select a placement mode

​Spill over between modes