> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-3121.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create sandboxes

> Create W&B Serverless Sandboxes that run code in isolated containers with their own filesystem, network, and process space.

<Warning>
  Serverless Sandboxes is in **public preview**. Access is enabled per organization. To request access for your organization, contact [support](mailto:support@wandb.com).
</Warning>

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](/sandboxes/file-access), network, and process space.

<Info>
  By default, sandboxes use `python:3.11` as the base image. To use a different image, pass `container_image` to [`Sandbox.run()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#run) or [`SandboxDefaults`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox-defaults). 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`.

  <Info>
    `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.
  </Info>

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

  ```python theme={null}
  from wandb.sandbox import Sandbox

  with Sandbox.run(container_image="python:3.14") as sandbox:
      sandbox.exec(["python", "--version"]).result()
  ```
</Info>

## Create a sandbox

Use [`Sandbox.run()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#run) to create and start a sandbox. This method returns a `Sandbox` object that you can use to interact with the environment.

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

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

```python theme={null}
from wandb.sandbox import Sandbox

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

To learn how to run commands inside a sandbox, see [Run commands](/sandboxes/run-commands). To learn about sandbox lifecycle and states, see [Sandbox lifecycle](/sandboxes/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.

```python theme={null}
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](/sandboxes/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](/sandboxes/lifecycle).

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

```python theme={null}
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:

```python theme={null}
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`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/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`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox-defaults) 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`):

```python theme={null}
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)
```