Create sandboxes - Weights & Biases Documentation

Serverless Sandboxes is in public preview. Access is enabled per organization. To request access for your organization, contact support.

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.Verify that the image and tag exist in the public registry before you use them. If the sandbox can’t pull the image, it doesn’t start and the client raises SandboxFailedError.

SandboxFailedError can occur for multiple reasons and doesn’t specifically identify an unavailable image. If you encounter this error, verify that the image and tag are available.

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

from wandb.sandbox import Sandbox

with Sandbox.run(container_image="python:3.14") 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)

​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