Documentation Index
Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
Use this file to discover all available pages before exploring further.
This guide covers using Session to manage multiple sandboxes with shared configuration.
What is a session?
A Session provides:
- Shared default configuration for all sandboxes
- Automatic cleanup when the session closes
- A scope for the
@session.function() decorator
Basic usage
import cwsandbox
from cwsandbox import SandboxDefaults
# Define shared configuration
defaults = SandboxDefaults(
container_image="python:3.11",
tags=("project-alpha",),
)
# Create a session with context manager
with cwsandbox.Session(defaults=defaults) 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
Creating sandboxes
session.sandbox()
Creates a sandbox with session defaults. The sandbox is not started until first use:
with cwsandbox.Session(defaults=defaults) as session:
# sandbox() returns an unstarted sandbox
sandbox = session.sandbox()
# Operations auto-start the sandbox on first use
result = sandbox.exec(["echo", "hello"]).result()
with cwsandbox.Session(defaults=defaults) as session:
sandbox = session.sandbox()
sandbox.start().result() # Explicit start
sandbox.wait() # Wait for RUNNING
result = sandbox.exec(["echo", "hello"]).result()
Overriding defaults
Pass additional arguments to override session defaults:
from cwsandbox import ResourceOptions
# Session with base configuration
defaults = SandboxDefaults(
container_image="python:3.11",
tags=("my-project",),
)
with cwsandbox.Session(defaults=defaults) 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
)
Multiple sandbox management
Sessions excel at managing sandbox pools:
with cwsandbox.Session(defaults=defaults) 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
Session lifecycle
Manual close
Close a session explicitly when not using context manager:
session = cwsandbox.Session(defaults=defaults)
sandbox = session.sandbox()
result = sandbox.exec(["echo", "hello"]).result()
# Close the session (stops all sandboxes)
session.close().result()
What close() does
- Stops all sandboxes created through the session
- Waits for cleanup to complete
- Returns
OperationRef[None]
Error handling
Sessions clean up even if exceptions occur:
with cwsandbox.Session(defaults=defaults) as session:
sandbox = session.sandbox()
raise RuntimeError("Something went wrong!")
# Sandbox is still cleaned up
Adopting external sandboxes
Bring sandboxes created outside the session under session management:
import cwsandbox
from cwsandbox import Sandbox
with cwsandbox.Session(defaults=defaults) as session:
# Find existing sandboxes
existing = Sandbox.list(tags=["orphaned-work"]).result()
# Adopt them for cleanup
for sandbox in existing:
session.adopt(sandbox)
# Now session.close() will clean them up too
Session properties
session = cwsandbox.Session(defaults=defaults)
# 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
For single sandboxes, sessions aren’t required:
from cwsandbox import Sandbox
# Direct usage without session
with Sandbox.run() as sandbox:
result = sandbox.exec(["echo", "hello"]).result()
# Cleanup handled by context manager
