Lifetime and cleanup¶

Use a context manager when the sandbox belongs to one block of work:

from sandweave import Sandbox

with Sandbox() as env:
    print(env.run("python -c 'print(42)'").stdout)

Leaving the block terminates the sandbox and discards unsaved state, including when the block raises an exception. Cache or snapshot before leaving if you need to retain state.

What happens when Python exits?¶

By default, a sandbox follows its creating Python process. It terminates when that process exits, including a crash or an IPython kernel shutdown. Local workers track process identity. For remote ownership, the SDK sends heartbeats automatically every five seconds. Workers and cluster controllers allow ten minutes without a successful renewal before expiring ownership. A longer network outage can therefore terminate an attached sandbox.

The ten-minute grace period requires Sandweave 0.2.11 or newer on workers and controllers. Restart older worker and controller processes after upgrading; upgrading only the client does not change their timeout.

Interrupting one notebook cell does not end the kernel. Its sandbox can remain running until you terminate it or shut down the kernel.

Keep an environment running¶

from sandweave import Sandbox

env = Sandbox(template="gnome", detached=True)
print(env.id)
env.close()

The environment survives this Python process exiting. Save its ID so you can reconnect later. Detached environments still respect ttl and explicit termination. A with Sandbox(detached=True) block still terminates its sandbox on exit.

Close, stop, or terminate?¶

Method	Effect
`env.close()`	Disconnect this Python handle. The sandbox's ownership and TTL still apply.
`env.terminate()`	Release the runtime and discard unsaved state. Existing caches and external volumes remain.
`env.delete()`	Terminate and remove private runtime files, logs, and recordings. Retain published snapshots, shared images, external mounts, and a small identity tombstone.
`env.stop()`	Save a checkpoint before releasing the runtime. Return a snapshot reference; if saving fails, preserve the source.
`env.pause()`	Suspend the resident sandbox while retaining its memory and GPU state.
`env.resume()`	Continue the same paused sandbox.

close() is why an environment can still appear as running in the dashboard after you disconnect. terminate() stops it; the dashboard can retain its record as terminated history.

Delete private files¶

env.delete()                  # Wait for cleanup, up to 300 seconds.
env.delete(wait=False)        # Return after the deletion request is persisted.
env.close()

Deletion is explicit and safe to repeat. Once acknowledged, cleanup continues after the client disconnects or exits. The worker retries failures and resumes pending deletions after restart; Weave also persists the request on its controller. timeout= limits how long this caller waits, without cancelling cleanup. Async callers can use await env.delete.aio(...). The CLI equivalent is sandweave delete SANDBOX_ID --target lab.

Export any recordings or logs you want to keep before deleting. Published snapshots and caches remain usable. Private files on an unavailable worker stay pending until that worker returns; they are not reported as deleted. Requires Sandweave 0.2.40 on the client, controller (when used), and workers.

For an environment acquired from a benchmark task, env.close() also releases its task lease and pool capacity. task.close() does the same; both are safe to repeat. A task context performs this cleanup on exit.

Reconnect¶

from sandweave import Sandbox

env = Sandbox.connect("SANDBOX_ID", target="lab")
print(env.run("python --version").stdout)
env.terminate()

Replace SANDBOX_ID with the saved ID and lab with the original target. Omit target for a local sandbox. Connecting borrows a handle; it does not transfer ownership or extend the original lifetime.

Leaving a with Sandbox.connect(...) block only disconnects the borrowed handle. It does not terminate the sandbox.

Add a lifetime limit¶

env = Sandbox(detached=True, ttl=300)

The five-minute TTL starts at readiness and counts time spent paused or disconnected. Automatic cleanup does not create a checkpoint.

CLI lifetime¶

sandweave run creates a sandbox for one command and terminates it afterward. sandweave create creates a detached environment. Use sandweave stop to save and stop it, or sandweave terminate to discard unsaved state.