Cleanup patterns

These examples use a CoreWeave API access token in CWSANDBOX_API_KEY. For Forge API key authentication, see Get started. For CKS requirements, see Placement modes. This guide covers resource management and cleanup strategies for sandboxes. Reliable cleanup prevents orphaned sandboxes after a script exits, which keeps costs predictable and avoids unintentional compute resource usage. The patterns here apply to scripts that create one or many sandboxes, with or without an explicit session.

Automatic cleanup

Automatic cleanup ties a sandbox’s lifetime to a Python construct (a context manager, or a session that the SDK closes when the process exits) so the SDK releases resources without explicit stop() calls. A sandbox you start with Sandbox.run() outside a session or context manager keeps running after your script exits, until its main command exits, you stop it, or its maximum lifetime expires.

Context managers (recommended)

Context managers are the recommended pattern because they guarantee cleanup even if the enclosed code raises an exception. The SDK stops sandboxes when the context exits:

from cwsandbox import Sandbox

with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# sandbox.stop() called automatically

Sessions clean up all their sandboxes:

import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(container_image="python:3.11")) as session:
    sb1 = session.sandbox()
    sb2 = session.sandbox()
# Both sandboxes stopped automatically

Global cleanup handlers

The SDK registers cleanup handlers that stop sandboxes owned by registered sessions when the process terminates. Standalone sandboxes created outside a session or context manager require explicit cleanup:

Scenario	Behavior
Normal script exit	`atexit` handler stops sandboxes in registered sessions
Ctrl+C (`SIGINT`)	Signal handler stops sandboxes in registered sessions
`SIGTERM`	Signal handler stops sandboxes in registered sessions
Second Ctrl+C	Force exit (prevents unresponsive shutdown)

The SDK installs these handlers when your code first creates a sandbox. The SIGINT and SIGTERM handlers install only from Python’s main thread. If your application manages its own signals, call cwsandbox.disable_signal_handlers() or set CWSANDBOX_DISABLE_SIGNAL_HANDLERS=1 before you create the first sandbox. The atexit handler still runs, but stopping sandboxes when a signal arrives becomes your application’s job.

Manual cleanup

Use manual cleanup when you need explicit control over when to release a sandbox or session. Manual cleanup lets you pass stop options or coordinate cleanup across long-running code.

Sandbox stop()

sandbox = Sandbox.run()
result = sandbox.exec(["echo", "hello"]).result()
sandbox.stop().result()

# With options
sandbox.stop(graceful_shutdown_seconds=30.0).result()
sandbox.stop(snapshot_on_stop=True).result()

Session close()

from cwsandbox import SandboxDefaults

session = cwsandbox.Session(SandboxDefaults(container_image="python:3.11"))
sandbox = session.sandbox()
# ...
session.close().result()  # Stops all sandboxes

Batch cleanup

from cwsandbox import results

sandboxes = [Sandbox.run() for _ in range(5)]
# ... use sandboxes ...
results([sb.stop() for sb in sandboxes])  # Stop all in parallel

Orphan management

Orphans are sandboxes left running unintentionally after the process that created them exits. A standalone sandbox that you keep running on purpose isn’t an orphan, but it becomes one if you lose track of it. The following sections describe how to make orphans easy to find, how to query for them, and how to bring them back under managed cleanup.

Tagging for discovery

For sandboxes in sessions and context managers, the SDK’s automatic cleanup prevents most orphans. Those sandboxes can still keep running after forced shutdowns (kill -9) or network failures. The cleanup handlers never stop a standalone sandbox, so it becomes an orphan if you forget to stop it. Use tags to make any orphans discoverable later.

from cwsandbox import Sandbox, SandboxDefaults

# Tag at creation time
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project", "batch-job-123"),
)

with Sandbox.run(defaults=defaults) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()

Good tagging practices:

Project or application name (my-project)
Job or run identifier (batch-job-123, run-2024-01-15)
Environment (dev, staging, prod)

Find orphaned sandboxes

Query by tags to find sandboxes from previous runs:

from cwsandbox import Sandbox

orphans = Sandbox.list(tags=["my-project"]).result()
for sandbox in orphans:
    sandbox.stop().result()

Session adoption

Adopting an orphan attaches it to a session so the session governs its lifetime. The orphan then receives the same automatic cleanup guarantees as newly created sandboxes. session.list() adds the session’s default tags to your filter, so it finds only sandboxes that carry them. To search without the session’s tags, use Sandbox.list() and adopt each result, as in the Sessions guide:

import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(container_image="python:3.11")) as session:
    orphans = session.list(tags=["my-project"]).result()
    for sandbox in orphans:
        session.adopt(sandbox)
# All adopted sandboxes cleaned up with session

Delete by ID

When you already know a sandbox’s ID, you can delete it directly without listing or adopting it first:

from cwsandbox import Sandbox

Sandbox.delete("sandbox-abc123").result()
Sandbox.delete("sandbox-abc123", missing_ok=True).result()  # Ignore if gone

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Automatic cleanup

Context managers (recommended)

Global cleanup handlers

Manual cleanup

Sandbox stop()

Session close()

Batch cleanup

Orphan management

Tagging for discovery

Find orphaned sandboxes

Session adoption

Delete by ID

​Automatic cleanup

​Context managers (recommended)

​Global cleanup handlers

​Manual cleanup

​Sandbox stop()

​Session close()

​Batch cleanup

​Orphan management

​Tagging for discovery

​Find orphaned sandboxes

​Session adoption

​Delete by ID

Automatic cleanup

Context managers (recommended)

Global cleanup handlers

Manual cleanup

Sandbox stop()

Session close()

Batch cleanup

Orphan management

Tagging for discovery

Find orphaned sandboxes

Session adoption

Delete by ID