cwsandbox-client

A Python client library for CWSandboxes.

Documentation

See the documentation site for the full tutorial, guides, and API reference.

Quick Start

from cwsandbox import Sandbox

# Quick one-liner with factory method (sync/async hybrid API)
sb = Sandbox.run("echo", "Hello, World!")
sb.stop().result()  # Block for completion

# Context manager for automatic cleanup
with Sandbox.run("sleep", "infinity", container_image="python:3.11") as sb:
    result = sb.exec(["python", "-c", "print(2 + 2)"]).result()
    print(result.stdout)  # 4

# Also works in async contexts
async with Sandbox.run("sleep", "infinity") as sb:
    result = await sb.exec(["python", "-c", "print(2 + 2)"])
    print(result.stdout)  # 4

Sandbox data connections

Exec, log, and file operations prefer a sandbox-scoped direct mTLS connection. Lifecycle and management operations continue to use the CWSandbox API. The SDK generates the private key in memory, sends only a certificate signing request, and never sends API bearer credentials to the sandbox data endpoint.

The default auto policy uses a short direct-connect budget, then falls back to the API gateway. You can require either path for validation or rollback:

from cwsandbox import DataPlaneMode, Sandbox, SandboxDefaults

# Fail instead of falling back, useful when validating direct connectivity.
with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sb:
    print(sb.exec(["echo", "direct"]).result().stdout)

# Disable direct access for a group of sandboxes.
defaults = SandboxDefaults(data_plane_mode=DataPlaneMode.GATEWAY)
with Sandbox.run(defaults=defaults) as sb:
    print(sb.exec(["echo", "gateway"]).result().stdout)

Direct credentials are scoped to the requested operation and created lazily. Active streams retain their connection, while a process-wide bounded idle-channel cache prevents large collections of inactive sandbox objects from retaining one socket per sandbox.

Authentication

Authentication defaults to AuthStrategy.COREWEAVE_API_KEY, which reads CWSANDBOX_API_KEY and sends it as a Bearer token. The strategy argument is optional, so existing callers do not need to change.

To use W&B credentials, install the optional integration and select it explicitly. Credential resolution is delegated to the W&B SDK and supports an active W&B session, WANDB_API_KEY, and the host-specific entry in .netrc:

pip install "cwsandbox[wandb]"

from cwsandbox import AuthStrategy, Sandbox

with Sandbox.run(auth=AuthStrategy.WANDB) as sb:
    ...

W&B authentication is sent in the x-wandb-api-key header; it is not treated as a CoreWeave Bearer token.

Embedding in a long-running host

Scripts and CLIs keep the default: the first owned sandbox registers atexit and, on the main thread, SIGINT/SIGTERM handlers so a signal can stop Sessions and exit.

Long-running hosts that already own process lifecycle should disable those signal handlers before creating a sandbox. atexit still runs on normal process exit. The host is responsible for graceful shutdown and for explicitly stopping sandboxes it owns.

import cwsandbox

cwsandbox.disable_signal_handlers()

CWSANDBOX_DISABLE_SIGNAL_HANDLERS=1

Accepted environment values: 1, true, yes, on (case-insensitive). Configure the API or environment variable before the first owned sandbox; changing the variable afterward has no effect.