Create sandboxes - Weights & Biases Documentation

W&B Sandboxes is in private preview, available by invitation only. To request enrollment, contact support or your AISE.

Create sandboxes with W&B. Each sandbox runs in its own container with its own filesystem, 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 ensure that the sandbox is stopped automatically when it exits the block, 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 is meant to run 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

Use Session to create and manage multiple sandboxes. When the session closes (for example, when exiting a with block), all sandboxes created by that session are stopped automatically. 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 that creates two sandboxes that use 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)

​Create a sandbox

​Start a sandbox without a main command

​Start a sandbox with a main command

​Create multiple sandboxes with a session

Create a sandbox

Start a sandbox without a main command

Start a sandbox with a main command

Create multiple sandboxes with a session