Create sandboxes

Learn how to create Serverless Sandboxes.

Serverless Sandboxes is in public preview.

Create W&B Serverless Sandboxes to run code in isolated environments. Start a single sandbox, run commands in it, and manage multiple sandboxes with a session. Each sandbox runs in its own container, with its own file system, network, and process space.

By default, sandboxes use python:3.11 as the base image. To use a different image, pass container_image to Sandbox.run() or SandboxDefaults. W&B supports public container images only.

The following code snippet creates a sandbox with the python:3.15 image and runs python --version inside it.

from wandb.sandbox import Sandbox

with Sandbox.run(container_image="python:3.15") as sandbox:
    sandbox.exec(["python", "--version"]).result()

Create a sandbox

Use Sandbox.run() to create and start a sandbox. This method returns a Sandbox object that you can use to interact with the environment.

W&B recommends using a context manager (with statement) to stop the sandbox automatically when the block exits, even if an error occurs.

The following example creates a sandbox with the default container image (python:3.11):

from wandb.sandbox import Sandbox

with Sandbox.run() as sandbox:
    print(sandbox)

To learn how to run commands inside a sandbox, see Run commands. To learn about sandbox lifecycle and states, see Sandbox lifecycle.

Start a sandbox without a main command

Call Sandbox.run() without a command when you want to create a sandbox first and run work inside it later.

from wandb.sandbox import Sandbox

with Sandbox.run() as sandbox:
    print(sandbox)

This pattern is useful for interactive and multi-step workflows. To learn how to run commands inside a sandbox, see Run commands.

Start a sandbox with a main command

You can also pass a command to Sandbox.run(). Use this pattern when the sandbox runs a single job from start to finish. When the main process exits, the sandbox enters a terminal state such as COMPLETED or FAILED.

The command you provide to Sandbox.run() starts as the sandbox’s main process.

from wandb.sandbox import Sandbox

sandbox = Sandbox.run("python", "train.py")

Sandbox.run() returns a Sandbox object that you can use to monitor the command and wait for it to finish. For example, to wait for the command to complete and retrieve its result:

from wandb.sandbox import Sandbox

sandbox = Sandbox.run("python", "train.py")

# Optionally wait for the command to complete
sandbox.wait_until_complete().result()

Create multiple sandboxes with a session

When you need more than one sandbox at a time, or want to share configuration across several sandboxes, use a session.

Use Session to create and manage multiple sandboxes. When the session closes (for example, when you exit a with block), it automatically stops all sandboxes it created.

You can optionally pass a SandboxDefaults object to a session to define reusable default configuration for all sandboxes created by that session. For example, you can specify a default container image, network configuration, or maximum lifetime for all sandboxes in the session.

session.sandbox() returns an unstarted sandbox. It auto-starts when you call Sandbox.exec(), Sandbox.read_file(), or any other operation.

The following code snippet creates a session with two sandboxes that share a default configuration (SandboxDefaults):

from wandb.sandbox import Session, SandboxDefaults

defaults = SandboxDefaults(
    container_image="python:3.11",
    max_lifetime_seconds=300,
    tags=("batch-job",),
)

with Session(defaults) as session:
    sandbox1 = session.sandbox()
    sandbox2 = session.sandbox()

    print(sandbox1)
    print(sandbox2)