Sessions

This guide covers using Session to manage multiple sandboxes with shared configuration. It’s for client developers who need to coordinate groups of sandboxes, apply common defaults, and ensure consistent cleanup across a workload.

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. Run the installation commands in an active Python virtual environment. 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.

Session overview

A Session provides:

Shared default configuration for all sandboxes.
Automatic cleanup when the session closes.
A scope for the @session.function() decorator.

Basic usage

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults

# Define shared configuration
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("project-alpha",),
    resources={"cpu": "1", "memory": "1Gi"},
)

# Create a session with context manager
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Create sandboxes through the session
    sb1 = session.sandbox()
    sb2 = session.sandbox()

    # Use the sandboxes
    result1 = sb1.exec(["echo", "sandbox 1"]).result()
    result2 = sb2.exec(["echo", "sandbox 2"]).result()

# All sandboxes automatically stopped when exiting context

Create sandboxes

The following sections describe how to create sandboxes through a session and override session defaults.

session.sandbox()

Creates a sandbox with session defaults. The sandbox doesn’t start until first use:

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # sandbox() returns an unstarted sandbox
    sandbox = session.sandbox()

    # Operations auto-start the sandbox on first use
    result = sandbox.exec(["echo", "hello"]).result()

For explicit control over when the start RPC fires:

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    sandbox = session.sandbox()
    sandbox.start().result()  # Explicit start
    sandbox.wait()            # Wait for RUNNING
    result = sandbox.exec(["echo", "hello"]).result()

Override defaults

Pass additional arguments to override session defaults:

from sandbox_auth import AUTH
from cwsandbox import ResourceOptions

# Session with base configuration
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project",),
    resources={"cpu": "1", "memory": "1Gi"},
)

with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Override image and resources for this sandbox
    gpu_sandbox = session.sandbox(
        command="sleep",
        args=["infinity"],
        container_image="pytorch/pytorch:latest",
        resources=ResourceOptions(
            requests={"cpu": "4", "memory": "16Gi"},
            limits={"cpu": "8", "memory": "32Gi"},
            gpu={"count": 1},
        ),
        tags=["gpu-workload"],  # Merged with session tags
    )

See the Sandbox configuration guide for all available options.

Multiple sandbox management

Sessions work well for managing sandbox pools:

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Create a pool of sandboxes
    sandboxes = [
        session.sandbox()
        for _ in range(5)
    ]

    # Distribute work across the pool
    processes = [
        sb.exec(["python", "-c", f"print({i})"])
        for i, sb in enumerate(sandboxes)
    ]

    # Collect results
    results = [p.result() for p in processes]

# All 5 sandboxes automatically cleaned up

To prepare sandboxes before requests arrive, see Implement a warm pool. The recipe maintains a buffer of ready sandboxes, gives each workload a separate sandbox, and replenishes the buffer as workloads claim them.

Session lifecycle

The following sections describe how to close a session, what close() does, and how to handle errors.

Manual close

When you don’t use a context manager, close a session explicitly:

from sandbox_auth import AUTH
session = cwsandbox.Session(defaults=defaults, auth=AUTH)

sandbox = session.sandbox()
result = sandbox.exec(["echo", "hello"]).result()

# Close the session (stops all sandboxes)
session.close().result()

What close() does

Calling close() performs the following actions:

Stops all sandboxes created through or adopted by the session.
Waits for cleanup to complete.
Returns OperationRef[None].

Error handling

Sessions clean up even if exceptions occur:

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    sandbox = session.sandbox()
    raise RuntimeError("Something went wrong!")
# Sandbox is still cleaned up

Adopt external sandboxes

Bring sandboxes created outside the session under session management:

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import Sandbox

with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Find existing sandboxes
    existing = Sandbox.list(tags=["orphaned-work"], auth=AUTH).result()

    # Adopt them for cleanup
    for sandbox in existing:
        session.adopt(sandbox)

    # Now session.close() will clean them up too

Session properties

Inspect session state with built-in properties such as sandbox_count:

from sandbox_auth import AUTH
session = cwsandbox.Session(defaults=defaults, auth=AUTH)

# Number of sandboxes tracked
print(session.sandbox_count)  # 0

sandbox = session.sandbox()
print(session.sandbox_count)  # 1

When to use sessions

Use case	Recommended approach
Single sandbox, simple task	`Sandbox.run()` with context manager
Multiple sandboxes, shared config	Session
Function decorator API	Session required
Pool of workers	Session
One-off command	Direct `Sandbox.run()`

Without sessions

You don’t need sessions for single sandboxes:

from sandbox_auth import AUTH
from cwsandbox import Sandbox

# Direct usage without session
with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# Cleanup handled by context manager

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Choose authentication

Session overview

Basic usage

Create sandboxes

session.sandbox()

Override defaults

Multiple sandbox management

Session lifecycle

Manual close

What close() does

Error handling

Adopt external sandboxes

Session properties

When to use sessions

Without sessions

​Choose authentication

​Session overview

​Basic usage

​Create sandboxes

​session.sandbox()

​Override defaults

​Multiple sandbox management

​Session lifecycle

​Manual close

​What close() does

​Error handling

​Adopt external sandboxes

​Session properties

​When to use sessions

​Without sessions

Choose authentication

Session overview

Basic usage

Create sandboxes

session.sandbox()

Override defaults

Multiple sandbox management

Session lifecycle

Manual close

What close() does

Error handling

Adopt external sandboxes

Session properties

When to use sessions

Without sessions