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.
Development
See DEVELOPMENT.md for setup and workflow.
For code standards and commit guidelines, see CONTRIBUTING.md.
License
- The CWSandbox Client library is licensed under the Apache-2.0 license.
- The CWSandbox Client examples are licensed under the BSD-3-Clause license.
Release files for cwsandbox 1.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cwsandbox-1.16.0.tar.gz | 658.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cwsandbox-1.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 916.0 kB
Release files / cwsandbox-1.16.0.tar.gz
| Download URL | cwsandbox-1.16.0.tar.gz |
|---|---|
| Size | 658.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
240b8bf574776e63c61dc2cdb86e9ce806dd5958b3cb29e22fe18afee60f2028
|
|
BLAKE2b-256 checksum How to use checksums |
d3b3d4fa8e6ba5e440b0af51c673db4a0f416f81eee89554011760dcafff45ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 25, 2026.
Transparency logRelease files / cwsandbox-1.16.0-py3-none-any.whl
| Download URL | cwsandbox-1.16.0-py3-none-any.whl |
|---|---|
| Size | 257.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5b0cb3257d630ea338d3c4dd3a10b24f562a82479239d7e6bdc8722b50d8001b
|
|
BLAKE2b-256 checksum How to use checksums |
b0cff98310d2b256962231099ffb22f7bb5624b1b05a5655a827f85a43393c9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 25, 2026.
Transparency log
