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.

W&B 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

The same API works in async contexts:

from sandbox_auth import AUTH
from cwsandbox import Sandbox

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

Next steps

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

Next steps

Get started

Tutorial

Guides

​Prepare your Python environment

​Choose authentication

​Quick start

​Next steps

Get started

Tutorial

Guides

Prepare your Python environment

Choose authentication

Quick start

Next steps