Get started with CoreWeave sandboxes

​

Choose a placement mode

​

Run a sandbox on serverless capacity

• Serverless enabled for your organization. If it isn’t, sandbox creation fails with CWSANDBOX_SERVERLESS_NOT_ALLOWED. Contact support to request access.
• A credential, either a CoreWeave API access token or a Weights & Biases API key. See Choose a credential.

​

Choose a credential

• The Python client has no built-in W&B credential path. Its built-in auth mode reads CWSANDBOX_API_KEY and sends it as a bearer token. To present a W&B key from Python, register your own auth mode with set_auth_mode.
• W&B Dedicated customers can’t reach serverless sandboxes with the API key from their dedicated instance. Supporting it is new authorization and billing work. Until then, use a CoreWeave access token if your organization is also a CoreWeave customer, or a W&B trial account.

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
export TOKEN="$CWSANDBOX_API_KEY"

export WANDB_API_KEY="[WANDB-API-KEY]"

uv pip install 'cwsandbox>=1.0.0'

from cwsandbox import Sandbox

with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "Hello!"]).result()
    print(result.stdout)

npm install @coreweave/cwsandbox

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

const client = createSandboxClientFromEnv();

const result = await client.withSandbox(async (sandbox) =>
  sandbox.commands.run(["echo", "Hello!"]),
);

console.log(result.stdout);

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClientFromEnv();

curl -X POST https://api.coreweave.com/v1/sandboxes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "containers": [
        {
          "name": "main",
          "image": "docker.io/library/python:3.12-slim",
          "command": "echo",
          "args": ["Hello!"],
          "resources": { "cpu": "500m", "memory": "512Mi" }
        }
      ]
    }
  }'

​

Deploy sandboxes on your own CKS cluster

• Deploy a runner and set the policy it carries.
• Run your first sandbox from the Python client.
• Delete the runner when you’re done.

​

Prerequisites

• A CKS cluster in your CoreWeave organization, in the STATUS_RUNNING state. View your clusters and their status on the Clusters page in the cloud console. Note the cluster’s zone and name. Both are reused in later steps.
• The SANDBOX_ADMIN action in Identity and Access Management (IAM), which lets you create runners and set their policy. Create or update an access policy that grants this action on the Access Policies page in the cloud console.
• A CoreWeave API access token. Generate one from the Tokens page in the cloud console and copy the Token Secret value. For more information about tokens, see Manage API Access Tokens.

cwic auth login

export TOKEN="[API-ACCESS-TOKEN]"

• The SANDBOX_USER IAM action, which lets you create sandboxes against the data plane. Granting SANDBOX_ADMIN also grants SANDBOX_USER.
• A CoreWeave API access token. For more information, see Manage API Access Tokens.
• Python 3.11 or newer in the environment that runs the SDK. The Python version inside the sandbox is independent and is set by the container_image you pass to Sandbox.run().

​

Deploy a runner and set its policy

{
  "displayName": "default",
  "constraints": {
    "resources": {
      "defaultCpu": "1",
      "defaultMemory": "2Gi",
      "maxCpu": "4",
      "maxMemory": "8Gi",
      "requireLimits": true
    },
    "network": {
      "defaultEgress": []
    },
    "security": {
      "allowPrivileged": false,
      "allowedRuntimeClasses": ["kata-qemu"],
      "defaultCpuRuntimeClass": "kata-qemu"
    },
    "lifecycle": { "defaultLifetimeSeconds": 900 }
  }
}

cwic sandbox runner create [RUNNER-ID]

cwic sandbox runner policy edit [RUNNER-ID] -f policy.json

cwic sandbox runner policy describe [RUNNER-ID]

curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": {
      "runnerId": "[RUNNER-ID]",
      "zone": "[ZONE]",
      "clusterName": "[CLUSTER-NAME]"
    },
    "managedSpec": {
      "releaseChannel": "RELEASE_CHANNEL_STABLE"
    },
    "policy": '"$(cat policy.json)"'
  }'

export RUNNER_ID="[RUNNER-ID]"

​

Run your first sandbox

• Cloud console: Open the cluster’s Sandbox runner card and watch the status badge until it shows Ready.
• cwic: Run cwic sandbox runner get [RUNNER-ID] and look for INSTALL to be READY. For a longer view, use cwic sandbox runner describe [RUNNER-ID].
• curl: Poll the runner until installStatus is READY:
  curl -H "Authorization: Bearer $TOKEN" \
    "https://api.coreweave.com/v1/sandbox/managedRunners/$RUNNER_ID" \
    | jq '{installStatus, connectionStatus}'
  

uv pip install 'cwsandbox>=1.0.0'

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

from cwsandbox import Sandbox

with Sandbox.run(placement_mode="cks") as sandbox:
    result = sandbox.exec(["echo", "Hello!"]).result()
    print(result.stdout)

• Sandbox.run() creates a sandbox and returns it inside a context manager. The sandbox tears down on context exit.
• exec() runs a command inside the sandbox and returns a Process object.
• .result() waits for the command to complete and returns the output.

with Sandbox.run(max_lifetime_seconds=7200) as sandbox:  # 2 hours
    ...

​

Disable the runner

cwic sandbox runner delete [RUNNER-ID]

curl -X DELETE https://api.coreweave.com/v1/sandbox/managedRunners/$RUNNER_ID \
  -H "Authorization: Bearer $TOKEN"

​

Spill over between modes

from cwsandbox import Sandbox

# Prefer your own cluster; fall back to serverless when it's full.
with Sandbox.run(placement_spillover="cks_then_serverless") as sandbox:
    print(sandbox.exec(["echo", "Hello!"]).result().stdout)

• cks_then_serverless requires placement_mode="cks" or an unset mode. An explicit placement_mode="serverless" raises ValueError.
• serverless_then_cks requires placement_mode="serverless" or an unset mode, and can’t be combined with runner_ids.
• Sandboxes created from a template accept only the default, strict, which honors placement_mode and never retries.

​

Next steps

• The Python client page introduces the SDK and links into reference material.
• The Python client tutorial walks through configuration, command execution, file operations, and cleanup.
• The Python client guides cover lifecycle, streaming, RL training, SWE-bench, SUNK integration, and other advanced topics.