Sandboxes Python client

The cwsandbox Python client provides a high-level SDK for creating and managing CoreWeave sandbox environments. It supports both synchronous and asynchronous workflows through a unified API.

Prepare your Python environment

Install uv. In your project directory, activate an existing Python 3.11 or later virtual environment, or create one:

uv venv --python 3.12
source .venv/bin/activate

Run the installation commands and example scripts from this environment.

Choose authentication

These examples run on serverless capacity unless a section specifies CKS. Choose the credential for the account that owns your sandboxes. See Choose and get credentials to obtain a key or token. Save the Python code from your credential tab as sandbox_auth.py beside the Python scripts you run from this page. It stores the authentication choice, not your credential. The examples import AUTH from that file and pass it explicitly to each new sandbox or session.

Forge API key
CoreWeave API access token

Use your Forge API key through the SDK’s W&B authentication strategy:

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Use the token for your CoreWeave organization:

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

For CKS placement, choose the CoreWeave token, enable a runner, and set placement_mode="cks" on sandbox creation or in SandboxDefaults. Creating a session with auth=AUTH also authenticates the sandboxes it owns. Keep the same credential when reconnecting, listing, or cleaning up sandboxes.

Quick start

Create a sandbox, run a command, and retrieve the result:

from sandbox_auth import AUTH
from cwsandbox import Sandbox

# Context manager for automatic cleanup
with Sandbox.run(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) as sb:
    result = sb.exec(["python", "-c", "print(2 + 2)"]).result()
    print(result.stdout)  # 4

In async code, use Sandbox(...) with async with to start the sandbox without blocking the event loop. Sandbox.run() calls start().result() internally, which blocks during startup. See Sync versus async patterns.

from sandbox_auth import AUTH
from cwsandbox import Sandbox

async with Sandbox(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sb:
    result = await sb.exec(["python", "-c", "print(2 + 2)"])
    print(result.stdout)  # 4

Migrate from `wandb.sandbox`

wandb.sandbox is deprecated. Use cwsandbox directly and select authentication explicitly. For account setup, follow the serverless quickstart.

Install and retain Forge authentication

These examples use a Forge SaaS API key on serverless capacity. For a dedicated instance, follow Use sandboxes with W&B Dedicated Cloud. In your active Python environment, install the standalone client and set your key. Replace [WANDB-API-KEY] with your Forge API key:

uv pip install 'cwsandbox>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

When you import the deprecated wrapper, it selects Forge authentication:

Before: wandb.sandbox

from wandb.sandbox import Sandbox

with Sandbox.run(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    result = sandbox.exec(["python", "-c", "print(2 + 2)"]).result()
    print(result.stdout)

With cwsandbox, pass the key through AuthHeaders. This route doesn’t require the optional wandb dependency:

After: cwsandbox

import os
from cwsandbox import AuthHeaders, Sandbox

forge_auth = AuthHeaders(
    headers={"x-wandb-api-key": os.environ["WANDB_API_KEY"]},
    strategy="wandb_api_key",
)

with Sandbox.run(
    auth=forge_auth,
    placement_mode="serverless",
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
    max_lifetime_seconds=43200,
) as sandbox:
    result = sandbox.exec(["python", "-c", "print(2 + 2)"]).result()
    print(result.stdout)

Save the migrated example as a file named migrated_sandbox.py, then run it:

python migrated_sandbox.py

Both examples print 4 and stop the sandbox when the with block exits. The migrated example sets max_lifetime_seconds=43200 explicitly to retain the wrapper’s 12-hour default. If your previous configuration selected a team or project, add x-entity-id or x-project-name to headers. Alternatively, follow Choose authentication to use the AuthStrategy.WANDB route. Install cwsandbox[wandb], import AuthStrategy, and pass auth=AuthStrategy.WANDB. This route uses the wandb dependency to resolve a configured session, WANDB_API_KEY, or credentials saved by wandb login. If no credential is configured, it can prompt you. It supports user API keys. The explicit AuthHeaders example reads WANDB_API_KEY through os.environ. That variable alone doesn’t change the client’s default authentication.

Review wrapper defaults

An import change alone doesn’t preserve all wrapper behavior:

Behavior	Migration action
Authentication	Pass `auth` explicitly. Without an explicit choice or an installed legacy override, `cwsandbox` reads a CoreWeave API access token from `CWSANDBOX_API_KEY`. The `wandb.sandbox` import installs a process-wide Forge authentication override. Remove remaining wrapper imports.
Maximum lifetime	If you need the wrapper’s 12-hour default, set `max_lifetime_seconds` on a sandbox or in `SandboxDefaults`. Otherwise, the server determines the default.
Secrets	The wrapper’s `Secret` defaults `store` to `"wandb-team-secrets"`. `cwsandbox.Secret` requires an explicit store. For Forge team secrets, use `Secret(store="wandb", name="[SECRET-NAME]")` with Forge authentication and serverless placement. See Use Forge secrets.

A CoreWeave API access token supports both serverless and CKS placement. For placement options and account requirements, see Sandbox placement and spillover. If your code uses profile selectors or discovery APIs, follow What changed from profiles and Discover available runners.

Next steps

Use the CLI guide to manage existing sandboxes from your terminal.

Get started

Authenticate and run your first serverless sandbox with the SDK.

Tutorial

Learn to configure sandboxes, run commands, transfer files, and clean up with the Python SDK.

Guides

In-depth guides about specific topics including lifecycle management, file operations, execution patterns, and troubleshooting.

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Prepare your Python environment

Choose authentication

Quick start

Migrate from `wandb.sandbox`

Install and retain Forge authentication

Review wrapper defaults

Next steps

Get started

Tutorial

Guides

​Prepare your Python environment

​Choose authentication

​Quick start

​Migrate from wandb.sandbox

​Install and retain Forge authentication

​Review wrapper defaults

​Next steps

Get started

Tutorial

Guides

Prepare your Python environment

Choose authentication

Quick start

Migrate from `wandb.sandbox`

Install and retain Forge authentication

Review wrapper defaults

Next steps