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
Command-line interface
Install the optional CLI to inspect and manage existing sandboxes from your terminal:
pip install "cwsandbox[cli]"
export CWSANDBOX_API_KEY="your-api-key"
export SANDBOX_ID="your-sandbox-id"
# Discover and inspect sandboxes
cwsandbox ls
cwsandbox get "$SANDBOX_ID"
# Run a command or open an interactive shell
cwsandbox exec "$SANDBOX_ID" python -c "print('hello')"
cwsandbox sh "$SANDBOX_ID"
# Inspect the main process logs, then stop the sandbox
cwsandbox logs "$SANDBOX_ID" --tail 100 --timestamps
cwsandbox stop "$SANDBOX_ID"
To authenticate with W&B instead, install cwsandbox[cli,wandb] and pass
--auth wandb (or set CWSANDBOX_AUTH=wandb). Credentials come from
WANDB_API_KEY or wandb login; choose the entity and project with
WANDB_ENTITY and WANDB_PROJECT:
WANDB_ENTITY=my-team cwsandbox --auth wandb ls
The CLI operates on sandboxes created with the Python SDK or another client. Run
cwsandbox --help or cwsandbox <command> --help for all commands and options.
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. It also falls back if direct credential negotiation returns an
INTERNAL error, before sending the data operation. Authentication and permission
errors remain fatal. 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.
The CLI accepts --data-plane-mode=auto|direct|gateway on exec, logs, sh,
files read, and files write, with auto as the default. Use gateway to skip
direct credential negotiation, or direct to require a direct connection:
cwsandbox exec --data-plane-mode=gateway "$SANDBOX_ID" -- nvidia-smi
cwsandbox logs --data-plane-mode=gateway "$SANDBOX_ID" --tail 100
cwsandbox sh --data-plane-mode=direct "$SANDBOX_ID"
cwsandbox files read --data-plane-mode=gateway "$SANDBOX_ID" /tmp/output.txt
For exec, put CLI options before -- and the remote command after it.
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:
...
Sandboxes are created in your default W&B entity unless you choose one. To pick
an entity (for example, a team in a different organization) or a project, pass
WandbAuth:
from cwsandbox import Sandbox, WandbAuth
with Sandbox.run(auth=WandbAuth(entity="my-team")) as sb:
...
The entity is resolved in this order: WandbAuth(entity=...), the active
wandb.run, then W&B settings such as WANDB_ENTITY. AuthStrategy.WANDB
is the same as WandbAuth().
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.19.1
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.19.1.tar.gz | 665.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cwsandbox-1.19.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 925.2 kB
Release files / cwsandbox-1.19.1.tar.gz
| Download URL | cwsandbox-1.19.1.tar.gz |
|---|---|
| Size | 665.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
227383aa0e7b768a80414f8bfaa3cb14750f4a1665f9b3b11079aa34f446c8e3
|
|
BLAKE2b-256 checksum How to use checksums |
3543985f2ea5885ef4c8a6c3d937292dfb5fe0778b6beb4916f7e760ba649b9d
|
| 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 Oct 13, 2026.
Transparency logRelease files / cwsandbox-1.19.1-py3-none-any.whl
| Download URL | cwsandbox-1.19.1-py3-none-any.whl |
|---|---|
| Size | 260.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9ad4870978fb45d6fe87d8e6d9b3b198b0f30c5357fdd9c8d786a277fe5fcb0d
|
|
BLAKE2b-256 checksum How to use checksums |
00460f93da9a466e69ef6b16986309c95c07137d244ee837a148bb287aafb9e3
|
| 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 Oct 13, 2026.
Transparency log
