Skip to main content
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.
from wandb.sandbox import Sandbox

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

​
Create a single 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 and get the result
result = 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. 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)